Skip to content

Installation

Superficially, enabling CLA Bot is done with including the CI/CD component in your project. Please visit your local CI/CD catalog to learn more about that. An overview should be available with your local GitLab instance.

However, things ain't that easy unfortunately. Even if you were to 'just include the component' (which we do not recommend), access tokens are required at the very least for CLA Bot to work. We strongly recommend one additional project (for 'home' and 'store', see Setup).

For setting up the required tokens and the webhook, you can either follow the manual install or use an installer. Because the installer requires several dependencies, you can either run it via CLA Bot's docker image or do a local install. Neither is required once installed and can safely be removed once done.

The recommended setup will have 'home' and 'store' combined in one additional project, separate from 'playground'. The CI/CD component will have to be added to the .gitlab-ci.yml inside 'home'. With the recommended setup, this will be the only step/stage inside this pipeline. The 'playground' will keep your existing CI/CD pipeline and not require any alterations. Storing the list of your known contributors happens via git commits/pushes and will also not clutter your 'playground's commit history. With our recommendation, this happens in this separate project, 'home' = 'store'. The alternative would be a separate branch within your existing project or directly with all its branches. This is not recommended and not supported by the installer.

To be clear: you can have a single project ('playground' = 'home' = 'store') but we strongly recommend one additional project for a cleaner and safer setup. Also, while 'home' and 'store' can be separate projects, we do not see any benefit for this.

The recommended setup is the one that is tested best, dragons are beyond that...

After covering the installation (steps) explained below, you will still have to include the component into the CI pipeline in 'home'.

Guided install

The Docker image of CLA Bot contains install-bot which is meant to support you installing CLA Bot. You can run it directly using podman (or docker) via

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

(or replace podman by docker, possibly separating pull/run, see snippet blow)

As an alternative, you can install CLA Bot's Python code via pip via

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

and run install-bot from that installation. Some sort of virtual environment is recommended for that. Note that even though CLA Bot is included in this installation, it is meant to be run from within a CI/CD pipeline of a project.

The "installer" will help setting up all required access tokens, trigger tokens, and webhooks. It will not change your CI/CD pipeline, instead provide a hint on how to include the CI/CD component.

installer screenshot

Note that not all options are currently supported by the installer. Should you encounter problems with the "installer" or find a feature missing, please do get in touch, better yet, open an issue.

Manual install

There are several steps required, possibly in more than one project (depending on how you choose the setup). In case you can configure inputs to the CI/CD component, those will be identified by [input].

  • Pick the project CLA Bot should monitor:

    1) Note its project id (int number)
    2) Decide your workflow: gitlab or papertrail [cla_process_via_gitlab]
    3) Tick the checkbox All threads must be resolved for "Settings/Merge Requests". This will block MRs as long as there are unresolved discussions.
    4) Create a project access token with scope "api" and role "maintainer" naming it "CLA Bot" (that is how it will show up as project member), note its content. Cherry on top: adjust the avatar of the "bot" (see below).

  • Create or pick a project to hold the signature store:

    5) Note its project URL (string, https link for git) [cla_store]
    6) Create a project access token with scope "read_repository, write_repository" and role "maintainer", note its content.
    7) Decide whether you want to store signature as .csv or SQLite file [cla_store_type]
    8) No need to create a directory structure or initial files, CLA Bot will take care of that, but pick a branch [cla_store_branch]

  • Create or pick a project that will contain the CI pipeline of CLA Bot:

    9) Note its project id (int number)
    10) Create a pipeline trigger token, note its content. The URL shown should be similar to https://gitlab.jsc.fz-juelich.de/api/v4/projects/PROJECT_ID/ref/REF_NAME/trigger/pipeline?token=TOKEN where PROJECT_ID is from step 9 and REF_NAME should correspond to the branch for step 13.
    11) Create project access token with scope "read_api" and role "maintainer", note its content.
    12) Create CI/CD variables to provide access to the projects for CLA Bot: Create a masked variable CLA_BOT_API_TOKEN_<id> where you use the id from step 1 and the token from step 4. Create a masked variable CLA_BOT_API_TOKEN and add the token from step 11 as content. Create a masked variable CLA_BOT_STORAGE_TOKEN with the token from step 6. (Since multiple projects may use a single signature store, the CLA_BOT_API_TOKEN has the project's id appended. Since there will only be one signature store, this is not required for the store token.)

  • Go back to the project to monitor

    13) Create a Webhook for event types "Merge Request events" and "Comments". The URL for the hook is that of step 10 using the corresponding token. It's best practice (and recommended) to mask this token. The first event type will be triggered on new MRs and additional commits, the second type will be triggered in case contributors add comments (required for the gitlab workflow).

  • Go back to the project with the bot's CI pipeline

    14) Create/extend the CI pipeline including the CLA Bot component, adjusting inputs with values noted in steps 1-13. The component should be limited to run for triggered pipelines only (possibly MRs), see snippet below. As an alternative for full control, include the bot's Docker image or the bot directly into your pipeline, copying the necessary calls to it from the template.
    Should you include CLA Bot directly in your project's CI/CD pipeline, make sure to set up rules for all steps to distinguish when CLA Bot and the remainder of your pipeline should run, i.e. the bot likely does not need to be executed with every push nor does the project's test suite and other steps have to be executed on every merge request event.
    15) Tune which project members or users should be allowed by CLA Bot [approved_roles, approved_users]

Including the CI/CD Component

At Forschungszentrum Jülich, you should find CLA Bot in the CI/CD Catalog, ready to be included into 'home's CI/CD pipeline. The steps explained above should cover all the required preparations for this. Please refer to the GitLab help pages for a general overview on how to include components. It should look similar to:

include:
  - component: $CI_SERVER_FQDN/rg-rse/components/cla-bot/CLA-Bot@0.4.2
    inputs:
      cla_store_url: "URL for 'store'"

Changes will be necessary for different inputs (the installer will provide hints) and changed paths, depending on where you obtain the component from. Please refer to the catalog for a concrete example.

The CI/CD Component does not exist on my GitLab instance

In this case there are two options: it is possible to mirror the component to your instance, providing it to all users. Alternatively, you can include the component remotely, directly addressing it on our instance. This may be obsolete if and when GitLab decides to allow remote includes in an easier way. Currently, our best bet is to include the component via

include:
  - remote: 'https://gitlab.jsc.fz-juelich.de/rg-rse/components/cla-bot/-/raw/master/templates/CLA-bot.yml'

Please note that this may cause issues with the docker image being found. If that is the case, please get in touch.

As third option, you can copy the job step from the template file of the component to your 'home' project. Make sure all variables are available and set up correctly (you won't need inputs) and make sure the script can be executed. Incorporating it directly into a CI/CD pipeline would replace including a component.

Notes

The above projects can all refer to a single project, then branches need to be chosen accordingly. The bot may commit (and mess up the commit history) or the CI pipeline could be protected from changes from non-maintainers. Likewise, the stored signatures should not be visible to just anyone.

Snippets

For running install-bot from the image, it may be required making Docker aware of the registry first. Try

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

to separate the pull/run calls. You may need to log in to the registry first.

For step 4
The avatar of CLA Bot can be changed with an access token (API) of the bot inside the project. An example avatar is provided in the repository. To install it, call the API

curl --request PUT --header "PRIVATE-TOKEN: <token>" \
     --form "avatar=@<image>" \
     --url "https://gitlab.jsc.fz-juelich.de/api/v4/user/avatar"

For step 13

rules:
  # Run on merges or trigger events
  - if: $CI_PIPELINE_SOURCE == "merge_request_event" || $CI_PIPELINE_SOURCE == "trigger"