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?

  1. 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.

  2. 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, or error).

    • Only if you are using GitHub Enterprise Server: Set enterprise_server to your server’s URL.

  3. In a new branch of your repository, create the .github/scripts/ directory if it does not already exist and add a script named start_analysis.sh. This script should call axivion_ci. Based on the rule added in the previous step, this run will also annotate the pull request with any findings.

  4. In the same branch, create the .github/workflows/ directory if it does not already exist and add an empty file named axivion.yml.

  5. Enter your desired GitHub Actions workflow into the axivion.yml file. 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 axivion tag to your runners, please change [self-hosted] to [self-hosted, axivion].

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

  6. 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.

  7. 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 error report 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 if axivion_ci returns a non-zero exit code, also enable abort_on_error in the AnnotateGitHubPR rule.

    • For the comment or request_changes report 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 check overview with failing Axivion Suite check

Status checks at the bottom of the PR. In this example, the Axivion Suite check fails due to identified issues.

An annotation about dead code posted by annotate_pr.

An annotation (error report type) shown within the diff (“Files changed”) tab.

A comment about a style violation posted by annotate_pr.

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.

Setting up branch rulesets to require GitHub Actions to pass.

Within the branch rulesets configuration, you can require Axivion Suite to complete successfully before a PR can be merged.