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 stand-alone 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] [-sts STORE_SCOPE] [-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)
  -sts STORE_SCOPE, --store-scope STORE_SCOPE
                        scope of CLA Store, private (single project) or global
                        (multiple projects) (string) [env var:
                        CLA_BOT_STORAGE_SCOPE] (default: private)
  -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.

manage-bot

This tool 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 \
   manage-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 manage-bot or rotate-bot a try (worst case scenario: you will have to change all tokens manually if it fails...)

install-bot

This can be used to install CLA-Bot without further interaction. All options need to be provided in a config file or via the command line (a combination of both also works, command line options take precedence). install-bot will follow the 'default path' and behave like manage-bot) but not query options. It will not fail gracefully or check for inconsistencies during execution!

As with manage-bot 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, otherwise the tool cannot interact with your GitLab instance. Provide it as command line argument or via a ENV variable.

Currently, the parameters to run install-bot are

usage: install-bot [-h] [-v] [-c CONFIG_FILE] -gi GITLAB_INSTANCE
                   -t ACCESS_TOKEN -pid PLAYGROUND_PROJECT_ID
                   -pm PLAYGROUND_TOKEN_NAME -pa | --playground-avatar |
                   --no-playground-avatar -cd CLA_URL -wf | --workflow |
                   --no-workflow -wh | --webhook | --no-webhook
                   [-hid HOME_PROJECT_ID] [-hns HOME_PROJECT_NAMESPACE]
                   [-hn HOME_PROJECT_NAME] [-hp HOME_PROJECT_PATH] -sh |
                   --store-home | --no-store-home [-sid STORE_PROJECT_ID]
                   [-sns STORE_PROJECT_NAMESPACE] [-sn STORE_PROJECT_NAME]
                   [-sp STORE_PROJECT_PATH] -sb STORE_GIT_BRANCH -saa |
                   --store-auto-approve-role | --no-store-auto-approve-role
                   [-sar STORE_APPROVE_ROLE] -st STORE_TYPE -sc | 
                   --store-scope-private | --no-store-scope-private

Run a fresh install of CLA-Bot. All options need to be provided either as
command line option, environment variable, or a configuration file.

options:
  -h, --help            show this help message and exit
  -v, --version         show version
  -c, --config-file CONFIG_FILE
                        config file to read options from (bot.conf)
  -gi, --gitlab-instance GITLAB_INSTANCE
                        GitLab instance to install/update on [env var: INSTANCE]
  -t ACCESS_TOKEN       personal access token (API) to interact with your GitLab
                        instance [env var: TOKEN]
  -pid, --playground-id PLAYGROUND_PROJECT_ID
                        project id for CLA-Bot's 'Playground'
  -pm, --playground-member PLAYGROUND_TOKEN_NAME
                        name of CLA-Bot inside its 'Playground'
  -pa, --playground-avatar, --no-playground-avatar
                        set an avatar image for CLA-Bot inside its 'Playground'
  -cd, --cla-url CLA_URL
                        URL of CLA
  -wf, --workflow, --no-workflow
                        whether or not to use the 'GitLab workflow'
  -wh, --webhook, --no-webhook
                        whether or not to install the webhook in 'Playground'
  -hid, --home-id HOME_PROJECT_ID
                        project id of CLA-Bot's existing 'Home'
  -hns, --home-namespace HOME_PROJECT_NAMESPACE
                        namespace to create 'Home' in
  -hn, --home-name HOME_PROJECT_NAME
                        name of 'Home' to create
  -hp, --home-path HOME_PROJECT_PATH
                        path (part of URL inside the namespace) of 'Home' to
                        create
  -sh, --store-home, --no-store-home
                        whether or not to use 'Home' == 'Store'
  -sid, --store-id STORE_PROJECT_ID
                        project id of CLA-Bot's existing 'Store'
  -sns, --store-namespace STORE_PROJECT_NAMESPACE
                        namespace to create 'Store' in
  -sn, --store-name STORE_PROJECT_NAME
                        name of 'Store' to create
  -sp, --store-path STORE_PROJECT_PATH
                        path (for URL) of 'Store' to create
  -sb, --store-branch STORE_GIT_BRANCH
                        name of git branch used in 'Store'
  -saa, --store-auto-approve-role, --no-store-auto-approve-role
                        whether to auto-approve GitLab roles
  -sar, --store-approve-role STORE_APPROVE_ROLE
                        GitLab role to auto-approve ((30) developer,
                        (40) maintainer, (50) owner)
  -st, --store-type STORE_TYPE
                        (csv or sql)
  -sc, --store-scope-private, --no-store-scope-private
                        whether to store signatures in private scope

Args that start with '--' can also be set in a config file (bot.conf or
specified via -c). Config file syntax allows: key=value, flag=true,
stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). In general,
command-line values override environment variables which override config file
values which override defaults.

extend-bot

This can be used to extend an already installed CLA-Bot with additional 'playgrounds' without further interaction. All options need to be provided in a config file or via the command line (a combination of both also works, command line options take precedence). extend-bot will follow the 'default path' and behave like manage-bot) but not query options. It will not fail gracefully or check for inconsistencies during execution!

As with manage-bot 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 \
   extend-bot

You will need a Personal Access Token, otherwise the tool cannot interact with your GitLab instance. Provide it as command line argument or via a ENV variable.

Currently, the parameters to run extend-bot are

usage: extend-bot [-h] [-v] [-c CONFIG_FILE] -gi GITLAB_INSTANCE -t ACCESS_TOKEN
                  -pid PLAYGROUND_PROJECT_ID -pm PLAYGROUND_TOKEN_NAME -pa |
                  --playground-avatar | --no-playground-avatar -cd CLA_URL -wf |
                  --workflow | --no-workflow -wh | --webhook | --no-webhook
                  -hid HOME_PROJECT_ID -sh | --store-home | --no-store-home
                  [-sid STORE_PROJECT_ID] -sb STORE_GIT_BRANCH -saa | 
                  --store-auto-approve-role | --no-store-auto-approve-role
                  [-sar STORE_APPROVE_ROLE] -st STORE_TYPE -sc |
                  --store-scope-private | --no-store-scope-private

Extend an installation of CLA-Bot. All options need to be provided either as
command line option, environment variable, or a configuration file.

options:
  -h, --help            show this help message and exit
  -v, --version         show version
  -c, --config-file CONFIG_FILE
                        config file to read options from (bot.conf)
  -gi, --gitlab-instance GITLAB_INSTANCE
                        GitLab instance to install/update on [env var: INSTANCE]
  -t ACCESS_TOKEN       personal access token (API) to interact with your GitLab
                        instance [env var: TOKEN]
  -pid, --playground-id PLAYGROUND_PROJECT_ID
                        project id for CLA-Bot's 'Playground'
  -pm, --playground-member PLAYGROUND_TOKEN_NAME
                        name of CLA-Bot inside its 'Playground'
  -pa, --playground-avatar, --no-playground-avatar
                        set an avatar image for CLA-Bot inside its 'Playground'
  -cd, --cla-url CLA_URL
                        URL of CLA
  -wf, --workflow, --no-workflow
                        whether or not to use the 'GitLab workflow'
  -wh, --webhook, --no-webhook
                        whether or not to install the webhook in 'Playground'
  -hid, --home-id HOME_PROJECT_ID
                        project id of CLA-Bot's existing 'Home'
  -sh, --store-home, --no-store-home
                        whether or not to use 'Home' == 'Store'
  -sid, --store-id STORE_PROJECT_ID
                        project id of CLA-Bot's existing 'Store'
  -sb, --store-branch STORE_GIT_BRANCH
                        name of git branch used in 'Store'
  -saa, --store-auto-approve-role, --no-store-auto-approve-role
                        whether to auto-approve GitLab roles
  -sar, --store-approve-role STORE_APPROVE_ROLE
                        GitLab role to auto-approve ((30) developer,
                        (40) maintainer, (50) owner)
  -st, --store-type STORE_TYPE
                        (csv or sql)
  -sc, --store-scope-private, --no-store-scope-private
                        whether to store signatures in private scope

Args that start with '--' can also be set in a config file (bot.conf or
specified via -c). Config file syntax allows: key=value, flag=true,
stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). In general,
command-line values override environment variables which override config file
values which override defaults.

rotate-bot

This can be used to rotate access tokens along with updating the CI/CD variables of CLA-Bot without further interaction. All options need to be provided in a config file or via the command line (a combination of both also works, command line options take precedence). rotate-bot will behave like manage-bot) but not query options. It will not fail gracefully or check for inconsistencies during execution!

Since a single 'home' can have multiple 'playgrounds', you can supply more than one project id as 'playground'. Either repeat the command line option or use a config file that includes a list [id1, id2, id3, ...].

As with manage-bot 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 \
   rotate-bot

You will need a Personal Access Token, otherwise the tool cannot interact with your GitLab instance. Provide it as command line argument or via a ENV variable.

Currently, the parameters to run rotate-bot are

usage: rotate-bot [-h] [-v] [-c CONFIG_FILE] -gi GITLAB_INSTANCE -t ACCESS_TOKEN
                  -pid PLAYGROUND_PROJECT_ID -pm PLAYGROUND_TOKEN_NAME
                  -hid HOME_PROJECT_ID -sh | --store-home | --no-store-home
                  [-sid STORE_PROJECT_ID]

Rotate tokens for an installation of CLA-Bot. All options need to be provided
either as command line option, environment variable, or a configuration file.

options:
  -h, --help            show this help message and exit
  -v, --version         show version
  -c, --config-file CONFIG_FILE
                        config file to read options from (bot.conf)
  -gi, --gitlab-instance GITLAB_INSTANCE
                        GitLab instance to install/update on [env var: INSTANCE]
  -t ACCESS_TOKEN       personal access token (API) to interact with your GitLab
                        instance [env var: TOKEN]
  -pid, --playground-id PLAYGROUND_PROJECT_ID
                        project id(s) for CLA-Bot's 'Playground'(s)
                        (multiple -pid or a list in the config file)
  -pm, --playground-member PLAYGROUND_TOKEN_NAME
                        name of CLA-Bot inside its 'Playground'
  -hid, --home-id HOME_PROJECT_ID
                        project id of CLA-Bot's existing 'Home'
  -sh, --store-home, --no-store-home
                        whether or not to use 'Home' == 'Store'
  -sid, --store-id STORE_PROJECT_ID
                        project id of CLA-Bot's existing 'Store'

Args that start with '--' can also be set in a config file (bot.conf or
specified via -c). Config file syntax allows: key=value, flag=true,
stuff=[a,b,c] (for details, see syntax at https://goo.gl/R74nmi). In general,
command-line values override environment variables which override config file
values which override defaults.