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.3.4
   # 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
   
     # This variable is a setting for post-archiving CodeMeta file updates.
     # If you don't have a CodeMeta file, you can remove the add_doi_codemeta
     # and CodeMeta2CFF jobs at the bottom of this file.
     ref: main
   
   # ╭────────────────────────────────────────────╮
   # │ 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
       outputs:
         record_doi: ${{steps.iga.outputs.record_doi}}
       steps:
         - uses: caltechlibrary/iga@v1
           id: iga
           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
     add_doi_codemeta:
       name: "Add ${{needs.run_iga.outputs.record_doi}} to codemeta.json"
       needs: run_iga
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
           with:
             ref: ${{ env.ref }}
         - name: Install sde
           run: pip install sde
         - name: Add DOI to CodeMeta File
           run: sde identifier ${{needs.run_iga.outputs.record_doi}} codemeta.json
         - name: Commit CFF
           uses: EndBug/add-and-commit@v9
           with:
             message: 'Add DOI to codemeta.json file'
             add: 'codemeta.json'
     CodeMeta2CFF:
       runs-on: ubuntu-latest
       needs: add_doi_codemeta
       steps:
         - name: Checkout
           uses: actions/checkout@v4
           with:
             ref: ${{ env.ref }}
         - name: Convert CFF
           uses: caltechlibrary/codemeta2cff@main
         - name: Commit CFF
           uses: EndBug/add-and-commit@v9
           with:
             message: 'Add updated CITATION.cff from codemeta.json file'
             add: 'CITATION.cff'
   

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. If you have a CodeMeta file, the GitHub action workflow can automatically add the DOI after IGA has run. The “ref” value is the branch where the CodeMeta file will be updated. If you don’t use a CodeMeta file, you can delete the add_doi_codemeta part of the workflow.

6. 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.