Skip to content

CLI Tools

Please note that this is still WiP, so not all options are fully implemented yet!

The CI/CD component relies on a Docker image that holds a couple of Python scripts. Please inspect those to assure you of what's happening with all your tokens! An installation that does not rely on the component or any existing Docker image would have to use the tools directly.

Likewise, a "non-gitlab workflow" will depend on you approving contributors by hand, e.g. adding their names and user ids to the 'store'. Only then will CLA-Bot be able to correctly check their status.

cla-bot

This is the main part, called from the CI/CD pipeline to take a look at MRs (or commits) added to 'playground'. cla-bot will identify a merge request to work on (from the trigger payload), connect to all three 'playground', 'home', and 'store' to then check contributors or record their approval of your CLA.

Since its tailored to run from a CI/CD pipeline, almost all its parameters are read from environment variables or trigger payloads. Should you find yourself executing it manually, you're either keen on testing its functionality - or you went astray. Call cla-bot -h to get a short help of the expected parameters.

add-cla

This is a standalone tool you call upon to manually add users to your list of known contributors. This is required unless you edit the database by hand or pick a "gitlab workflow". Since it is not meant to run from a CI/CD pipeline, you will have to provide all parameters by hand. While it will read the same environment variables, those are likely not set up in your shell.

To execute add-cla, either install the Python package in a virtual environment via

pip install -U \
   git+https://gitlab.jsc.fz-juelich.de/rg-rse/components/cla-bot.git@master

or call it from the Docker image, e.g.

podman run --rm --pull=always -it \
   registry.jsc.fz-juelich.de/rg-rse/components/cla-bot/pit-image:latest \
   add-cla

Currently, the parameters to run add-cla are

usage: add-cla [-h] [-n] [-sb STORE_BRANCH] [-sty STORE_TYPE] -pp PLAYGROUND_ID
               -sp STORE_URL -st STORE_TOKEN [--name NAME] [--id UID]
               [--email EMAIL] [--unique] [-v]

Use CLA-bot to manually add signatures to the database. This is really only
useful when using a paper trail instead of a fully gitlab integrated workflow.

options:
  -h, --help            show this help message and exit
  -n, --dry-run         only perform dry run, do not alter project (default:
                        False)
  -sb STORE_BRANCH, --store-branch STORE_BRANCH
                        branch inside CLA store to commit data to (string)
                        [env var: CLA_BOT_STORAGE_BRANCH] (default: main)
  -sty STORE_TYPE, --store-type STORE_TYPE
                        type of CLA Store, csv or SQLite (string) [env var:
                        CLA_BOT_STORAGE_TYPE] (default: csv)
  -pp PLAYGROUND_ID, --Playground PLAYGROUND_ID
                        PLAYGROUND project to record contributors for (numeric
                        id) [env var: CLA_BOT_PLAYGROUND] (default: None)
  -sp STORE_URL, --store STORE_URL
                        project to store CLA signatures (URL) [env var:
                        CLA_BOT_STORAGE_PROJECT] (default: None)
  -st STORE_TOKEN, --store-token STORE_TOKEN
                        access token (repository) to access the CLA store
                        project [env var: CLA_BOT_STORAGE_TOKEN] (default:
                        None)
  --name NAME           name of contributor (may be extracted from
                        $CI_COMMIT_MESSAGE) (default: None)
  --id UID              gitlab user_id of contributor (may be extracted from
                        $CI_COMMIT_MESSAGE) (default: None)
  --email EMAIL         email of contributor (may be extracted from
                        $CI_COMMIT_MESSAGE) (default: None)
  --unique              is the contributor an indiviual or signing on behalf
                        of an institution? (may be extracted from
                        $CI_COMMIT_MESSAGE) (default: True)
  -v, --version         show version

 In general, command-line values override environment variables which override
defaults.

install-bot

This tools can be used to:

  1. help you install CLA-Bot
  2. extend an already installed bot with additional 'playgrounds'
  3. rotate access tokens along with updating the CI/CD variables

As with add-cla either pip install or Docker run it

podman run --rm --pull=always -it \
   registry.jsc.fz-juelich.de/rg-rse/components/cla-bot/pit-image:latest \
   install-bot

You will need a Personal Access Token for any of its use cases. Otherwise the tool cannot interact with your GitLab instance.

During the initial installation, only a single 'playground' is supported. Please execute the installation script again to add additional projects to monitor MRs for. As mentioned with the general setup, you can monitor multiple projects of your group with different contributors.

Since Personal Access Tokens will expire at some point, you will need to either create new access tokens or rotate their values. Do not forget to update he matching CI/CD variables that store their values or CLA-Bot will stop working. To aid with that, you can also give install-bot a try (worst case scenario: you will have to change all tokens manually if it fails...)