8.2.5. GitLab CI/CD Integration

8.2.5.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.5.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 guidance (except for setting up the Axivion Suite). Add a tag axivion to it to indicate that this runner will be used for 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 general_options.keep_issues to ALL, since code quality reports should cover every issue, not just those introduced in the current 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 your project’s merge requests. This can be a Project Access Token (recommended), a Personal Access Token, or a Group Access Token. The token should be assigned the “Reporter” role and requires the 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”, enter “AXIVION_GITLAB_TOKEN”, and under “Value”, enter the access token.

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

  6. In the same branch, add an empty file called .gitlab-ci.yml to the root of your repository if one does not already exist.

  7. Add a job executing your desired workflow to this file. A recommended minimal template to run the analysis (which then also annotates the merge 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 progress of the new CI job under the “Pipelines” tab.

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

    • Even if the run is successful, it is recommended to review the output of each step to ensure the setup is working correctly.

  9. Finally, you may want to enforce that all findings are handled before allowing an MR to be merged. You can configure this in the merge check settings (Settings -> Merge requests -> Merge checks):

    • For the discussion_notes report type: Enable “All threads must be resolved”. This ensures that developers must resolve every comment added by the Axivion Suite before they can merge the branch.

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

8.2.5.3. Minimal workflow template

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

axivion_analysis:
   tags: [axivion]
   rules:
      # Don't run on draft MRs (requires GitLab 17.10+)
      - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_DRAFT == "true"
        when: never
      - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      # 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:
      - ./.gitlab/scripts/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 those 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.5.4. Screenshots

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

Code Quality Report with eight issues being found.

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.

A discussion note about a style violation posted by annotate_pr.

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 posted by annotate_pr.

A summary comment (via general_options.report_as_one_comment) shown in 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.

Setting up checks that must pass before merge requests can be merged.

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