Installation

IGA can be installed as either (or both) a command-line program on your computer or a GitHub Action in a GitHub repository.

IGA as a normal program

Please choose an approach that suits your situation and preferences. Then, after installation, proceed to (1) get an InvenioRDM token and (2) configure IGA for command-line use.

Installation alternative 1: installing IGA using pipx

Pipx lets you install Python programs in a way that isolates Python dependencies from other Python programs on your system, and yet the resulting iga command can be run from any shell and directory – like any normal program on your computer. If you use pipx on your system, you can install IGA with the following command:

pipx install iga

Installation alternative 2: installing IGA using pip

IGA is available from the Python package repository PyPI and can be installed using pip:

python3 -m pip install iga

As an alternative to getting it from PyPI, you can install iga directly from GitHub:

python3 -m pip install git+https://github.com/caltechlibrary/iga.git

If you already installed IGA once before, and want to update to the latest version, add --upgrade to the end of either command line above.

Installation alternative 3: installing IGA from sources

If you prefer to install IGA directly from the source code, first obtain a copy by either downloading the source archive from the IGA releases page on GitHub, or by using git to clone the repository to a location on your computer. For example,

git clone https://github.com/caltechlibrary/iga

Next, after getting a copy of the files, run setup.py inside the code directory:

cd iga
python3 setup.py install

IGA as a GitHub workflow

A GitHub Actions workflow is an automated process that runs on GitHub’s servers under control of a file in your repository. Follow these steps to create the IGA workflow file:

1. In the main branch of your GitHub repository, create a .github/workflows directory

2. In the .github/workflows directory, create a file named (e.g.) iga.yml and copy the following content (which is also available as file sample-workflow.yml in the GitHub repository for IGA):

   # GitHub Actions workflow for InvenioRDM GitHub Archiver version 1.2.2
   # This is available as the file "sample-workflow.yml" from the open-
   # source repository for IGA at https://github.com/caltechlibrary/iga/.
   
   # ╭────────────────────────────────────────────╮
   # │ Configure this section                     │
   # ╰────────────────────────────────────────────╯
   
   env:
     # 👋🏻 Set the next variable to your InvenioRDM server address 👋🏻
     INVENIO_SERVER: https://your-invenio-server.org
   
     # Set to an InvenioRDM record ID to mark release as a new version.
     parent_record: none
   
     # The variables below are other IGA options. Please see the docs.
     community:     none
     draft:         false
     all_assets:    false
     all_metadata:  false
     debug:         false
   
   # ╭────────────────────────────────────────────╮
   # │ The rest of this file should be left as-is │
   # ╰────────────────────────────────────────────╯
   
   name: InvenioRDM GitHub Archiver
   on:
     release:
       types: [published]
     workflow_dispatch:
       inputs:
         release_tag:
           description: "The release tag (empty = latest):"
         parent_record:
           description: "ID of parent record (for versioning):"
         community:
           description: "Name of InvenioRDM community (if any):"
         draft:
           description: "Mark the record as a draft"
           type: boolean
         all_assets:
           description: "Attach all GitHub assets"
           type: boolean
         all_metadata:
           description: "Include additional GitHub metadata"
           type: boolean
         debug:
           description: "Print debug info in the GitHub log"
           type: boolean
   
   run-name: Archive ${{inputs.release_tag || 'latest release'}} in InvenioRDM
   jobs:
     run_iga:
       name: "Send to ${{needs.get_repository.outputs.server}}"
       runs-on: ubuntu-latest
       needs: get_repository
       steps:
         - uses: caltechlibrary/iga@main
           with:
             INVENIO_SERVER: ${{env.INVENIO_SERVER}}
             INVENIO_TOKEN:  ${{secrets.INVENIO_TOKEN}}
             all_assets:     ${{github.event.inputs.all_assets || env.all_assets}}
             all_metadata:   ${{github.event.inputs.all_metadata || env.all_metadata}}
             debug:          ${{github.event.inputs.debug || env.debug}}
             draft:          ${{github.event.inputs.draft || env.draft}}
             community:      ${{github.event.inputs.community || env.community}}
             parent_record:  ${{github.event.inputs.parent_record || env.parent_record}}
             release_tag:    ${{github.event.inputs.release_tag || 'latest'}}
     get_repository:
       name: "Get repository name"
       runs-on: ubuntu-latest
       outputs:
         server: ${{steps.parse.outputs.host}}
       steps:
         - name: Extract name from INVENIO_SERVER
           id: parse
           run: echo "host=$(cut -d'/' -f3 <<< ${{env.INVENIO_SERVER}} | cut -d':' -f1)" >> $GITHUB_OUTPUT
   

3. Edit the value of the INVENIO_SERVER variable near the top of the file above ↑. For CaltechDATA the value should be https://data.caltech.edu.

4. Optionally, change the values of other options (parent_record, community, etc.)

5. Save the file, commit the changes to git, and push your changes to GitHub

Once you have installed the GitHub Action workflow for IGA, the next steps are (1) get an InvenioRDM token and (2) configure the GitHub Action workflow.