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?¶
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
axivionto it to indicate that this runner will be used for Axivion-related jobs.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, orcode_quality). If you are usingcode_qualityreports, you should also set general_options.keep_issues toALL, since code quality reports should cover every issue, not just those introduced in the current merge request.Set the
warning_exit_codeto 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_qualityreports: Setcode_quality_report_filenametoaxivion_code_quality.json(in accordance with the template below). Set thecode_quality_default_severityandcode_quality_severity_mapto non-default values if you have custom requirements.If you are not using the default
gitlab.comserver, replace theservervalue with$(GITLAB_SERVER). The actual URL will then be substituted during the CI run. Alternatively, set theservervalue to your server’s URL directly.
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, andwrite_repository.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.
In a new branch of your repository, add a script called
start_analysis.shto the.gitlab/scripts/directory (which you must create if it does not yet exist). This script should callaxivion_ci. Thanks to the rule added in the previous step, the same run will also annotate the merge request with any findings.You can give this script a different name than
start_analysis.shand place it in another location if you prefer. Just remember to make the necessary changes to the template later on.The checkout has no branch, so the Git branch must be determined at the top of the script and referenced as /Project/VCSIntegration/Git/branch; see Determining the branch in a CI system.
In the same branch, add an empty file called
.gitlab-ci.ymlto the root of your repository if one does not already exist.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.
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.
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_notesreport 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:
general_options.fail_if_issues_exist must be set to True.
abort_on_errormust be set to True.Make sure that
failure_exit_codeis set to a non-zero value (this is the default).
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 (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 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.¶
Here (within Settings->Merge requests->Merge checks), you can require the Axivion Suite to run successfully before a merge request can be merged.¶