8.2.4. GitHub Actions Integration¶
8.2.4.1. Background¶
You have a running Axivion Suite configuration.
Additionally, you want to integrate Axivion findings into GitHub pull requests via GitHub Actions.
8.2.4.2. What needs to be done?¶
Set up at least one server to function as a GitHub Actions runner. Install and properly configure Axivion Suite on this server so that all necessary tools (e.g.,
axivion_ci) are available. For instructions on setting up GitHub Actions runners and adding them to a repository, refer to GitHub’s documentation (excluding the Axivion Suite setup).If you already have or plan to have additional runners that are not supposed to run Axivion Suite, please add a tag (such as
axivion) to your runners during setup.
Add an annotate_pr rule to the PostCIActions of your configuration. For GitHub, this is the AnnotateGitHubPR rule. Here, you configure how findings are reported. In particular, you should:
Set the
report_type(comment,request_changes,warning, orerror).Only if you are using GitHub Enterprise Server: Set
enterprise_serverto your server’s URL.
In a new branch of your repository, create the
.github/scripts/directory if it does not already exist and add a script namedstart_analysis.sh. This script should callaxivion_ci. Based on the rule added in the previous step, this run will also annotate the pull request with any findings.You may name the script differently or place it in another location; however, ensure you make the corresponding changes to the template later.
actions/checkoutleaves the workspace without a 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, create the
.github/workflows/directory if it does not already exist and add an empty file namedaxivion.yml.Enter your desired GitHub Actions workflow into the
axivion.ymlfile. A recommended minimal template for running the analysis and annotating the pull request is available in Minimal workflow template. Further documentation from GitHub is available here.If you previously added an
axiviontag to your runners, please change[self-hosted]to[self-hosted, axivion].Please read through the template and replace any placeholder values.
Create a pull request for your new branch. After a short time, the progress of the new CI workflow will be visible under the “Checks” tab.
Any findings within the PR changes should now be visible in the overview (see Screenshots).
Even if the run succeeds, 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 a PR can be merged. Depending on the report type, there are two ways to achieve this:
For the
errorreport type: Enable status checks for Axivion Suite in your branch rulesets. To do this, enable “Require status checks to pass” and add the “Axivion Suite Analysis” check at the bottom (see Screenshots for details). Since the check only fails ifaxivion_cireturns a non-zero exit code, also enable abort_on_error in the AnnotateGitHubPR rule.For the
commentorrequest_changesreport type: Enable “Require a pull request before merging” and then enable “Require conversation resolution before merging” in the resulting submenu. This ensures that developers must resolve every comment added by Axivion Suite before merging the branch.
8.2.4.3. Minimal workflow template¶
A minimal pipeline definition using Axivion Suite with annotate_pr could look like this:
name: Axivion Suite
# Trigger on pull requests to the `main` branch.
on:
pull_request:
branches: [main]
jobs:
axivion_analysis:
name: Axivion Suite Analysis
runs-on: [self-hosted]
# Alternatively (if you defined a label):
# runs-on: [self-hosted, axivion]
permissions:
contents: read
pull-requests: write # To add comments
# This job will only be run when the PR is not a draft AND has not been closed (i.e., dropped without being merged).
if: ${{ !github.event.pull_request.draft && (github.event.pull_request.state != 'closed' || github.event.pull_request.merged) }}
steps:
- name: Clone repository
uses: actions/checkout@v4
- name: Confirm that Axivion Suite works
run: axivion_suite_info
# axivion_ci runs the analysis and, via the AnnotateGitHubPR rule, annotates the PR with any findings.
- name: Run Axivion CI
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_REPOSITORY: ${{ github.repository }}
GITHUB_PULL_REQUEST: ${{ github.event.number }}
run: ./.github/scripts/start_analysis.sh
Note
The AnnotateGitHubPR 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 prefer to 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), refer to Generating review comments with annotate_pr.
8.2.4.4. Screenshots¶
The following screenshots demonstrate this integration in action.
Status checks at the bottom of the PR. In this example, the Axivion Suite check fails due to identified issues.¶
An annotation (error report type) shown within the diff (“Files changed”) tab.¶
A comment (comment/request_changes report type) shown on the PR overview tab. These types of comments are also included in the diff (“Files changed”) tab.¶
Within the branch rulesets configuration, you can require Axivion Suite to complete successfully before a PR can be merged.¶