8.2.4. GitLab CI/CD Integration

8.2.4.1. Background

• You have a running Axivion Suite configuration.

• Additionally, you want to integrate Axivion findings into GitLab merge requests via GitLab CI/CD.

8.2.4.2. What needs to be done?

1. Set up at least one server to function as a GitLab CI/CD runner. On this server, the Axivion Suite should be installed and properly configured, such that all necessary tools (e.g., annotate_pr) are available. You can follow GitLab’s documentation on how to set up GitLab runners and register them for this (except for setting up the Axivion Suite). Add a tag axivion to it to indicate that we will use this runner to run the Axivion-related jobs.

2. Add an annotate_pr rule to the PostCIActions of your configuration. For GitLab, this is the AnnotateGitLabPR rule. Here, you configure how findings are reported. In particular, you should:

   • Set the report type (discussion_notes, regular_notes, or code_quality). If you are using code_quality reports, you should also set keep_issues to ALL, since code quality reports should cover every issue, not just those introduced in the respective merge request.

   • Set the warning_exit_code to 7, assuming you are using the template provided below. This way, warnings will be highlighted without being treated as errors.

   • Only if you are using code_quality reports: Set code_quality_report_filename to axivion_code_quality.json (in accordance with the template below). Set the code_quality_default_severity and code_quality_severity_map to non-default values if you have custom requirements.

   • If you are not using the default gitlab.com server, replace the server value with $(GITLAB_SERVER). The actual URL will then be substituted during the CI run. Alternatively, set the server value to your server’s URL directly.

3. Create a GitLab access token that can leave comments/reports on merge requests of your project. This can either be a Project Access Token (recommended), a Personal Access Token, or a Group Access Token. The token should be assigned the role of “Reporter” and needs scopes api, read_repository, and write_repository.

4. Set up a CI/CD variable for the access token you just created. Set the variable to “Masked” or “Masked and hidden”, but do not enable “Protect variable”. Under “Key”, write “AXIVION_GITLAB_TOKEN”, and under “Value”, enter the access token.

5. In a new branch of your repository, add a new script called start_analysis.sh to the .gitlab/scripts/ directory (which you have to create if it doesn’t exist yet). This script should call axivion_ci. Thanks to the rule you added in the previous step, the same run will also annotate the pull request with any findings.

   • You can call this script something else than start_analysis.sh, and you can place it in another location, if you’d like. Just keep in mind to make the necessary changes to the template later on.

6. In the same branch, add an empty file called .gitlab-ci.yml to the root of your repository if you do not have such a file yet.

7. Add a job executing your desired workflow to this file. A recommended minimal template to run the analysis (which then also annotates the pull request) is available below, in Minimal workflow template. Additional documentation from GitLab on Jobs is available here.

   • Please read through the template carefully and replace any placeholder values.

8. Create a Merge Request for your new branch. After a short while, you should be able to view the ongoing process of the new CI job under the “Pipelines” tab.

   • If there are any findings within the changes of the MR, they should be visible in the overview now (see Screenshots).

   • Even if the run is successful, it is recommended to read through the output of each step and to make sure the setup works correctly.

9. Finally, you might want to enforce that all findings must be handled before allowing a MR to be merged. You can set up the following in the merge check settings (Settings -> Merge requests -> Merge checks):

   • For the discussion_notes report type: Enable “All threads must be resolved”. This makes sure that developers will have to resolve every comment added by the Axivion Suite before being able to merge the branch.

   • For any report type: Enable “Pipelines must succeed” to forbid an MR from being merged while any pipeline reports an error. To ensure that the pipeline reports an error when it encounters any issues (and hence block merges before all issues are resolved), set the following options within the rule configuration:

     • fail_if_issues_exist needs to be set to True.

     • abort_on_error needs to be set to True.

     • Make sure that failure_exit_code is set to a non-zero value (this is the default).

8.2.4.3. Minimal workflow template

A minimal pipeline definition using the Axivion Suite with annotate_pr could look like this:

axivion_analysis:
tags: [axivion]
rules:
   - if: $CI_PIPELINE_SOURCE == "merge_request_event"
   # Don't run on draft MRs (requires GitLab 17.10+)
   - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_DRAFT == "true"
     when: never
   # Only for the code_quality report type: also run on the default branch to produce the base report
   # - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variables:
   GITLAB_SERVER: "$CI_SERVER_URL"
   GITLAB_PROJECT: "$CI_PROJECT_PATH"
   GITLAB_MERGE_REQUEST_IID: "$CI_MERGE_REQUEST_IID"
   GITLAB_TOKEN: "$AXIVION_GITLAB_TOKEN"  # PAT with scope "api"
script:
   - ./start_analysis.sh
# Only for the code_quality report type: pick up code quality artifact
# artifacts:
#    reports:
#       codequality: axivion_code_quality.json
allow_failure:
   exit_codes: [7] # = WARNING_EXIT_CODE (set in the rule)

Note

The AnnotateGitLabPR rule offers several more configuration options than are shown here. Refer to Generating review comments with annotate_pr and the rule’s description within your configuration for an overview. If you would rather run annotate_pr as a separate command-line step instead of as a rule (e.g., to report findings on a different CI system than the one running the analysis), this is described in Generating review comments with annotate_pr.

8.2.4.4. Screenshots

To see what this integration looks like in action, here are a few screenshots of it.

Code Quality Report (code_quality report type) at the bottom of the merge request. Here, the Axivion Suite found eight style violations of various severities. These findings will also be displayed inline in the MR diff.

Discussion note (discussion_notes report type) for a specific line of code, shown in the MR overview. These notes will also be displayed inline in the MR diff.

A summary comment (via report_as_one_comment) shown on the MR overview. This will be the only comment annotate_pr posts when this option is configured and will not be visible in the diff.

Here (within Settings->Merge requests->Merge checks), you can require the Axivion Suite to successfully run before a merge request can be merged.