8.2.2. GitHub Actions Integration

8.2.2.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.2.2. What needs to be done?

1. Set up at least one server to function as a GitHub Actions 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 GitHub’s documentation on how to set up GitHub Actions runners and add them to the repository for this (except for setting up the Axivion Suite).

   • If you already have (or are planning to have) additional runners that are not supposed to run the Axivion Suite, please add a tag (such as axivion) to your runners during setup.

2. In a new branch of your repository, add a new script called start_analysis.sh to the .github/scripts/ directory (which you have to create if it doesn’t exist yet). This script should call axivion_ci and produce either an AR file or report its findings to an Axivion Dashboard instance.

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

3. In the same branch, add an empty file called axivion.yml to the .github/workflows/ directory (which you have to create if it doesn’t exist yet).

4. Enter your desired GitHub Actions workflow into this axivion.yml file. A recommended minimal template to run the analysis as well as annotate_pr is available below, in Minimal workflow template. Additional documentation from GitHub is available here.

   • If you previously added an axivion tag to your runners, please change [self-hosted] to [self-hosted, axivion].

   • There are two possible configurations, depending on whether you use a Dashboard for the findings or output them into an AR file. [1] Please pick one of the two configurations and remove the steps for the other one. For the Dashboard configuration, you will additionally need to set up a secret containing a Dashboard API token called DASHBOARD_API_TOKEN.

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

5. Create a Pull Request for your new branch. After a short while, you should be able to view the ongoing process of the new CI workflow under the “Checks” tab.

   • If there are any findings within the changes of the PR, 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.

6. Finally, you might want to enforce that all findings must be handled before allowing a PR to be merged. Depending on the report type, there are two ways to go about this:

   • For the error report type: Enable status checks for the 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 the Screenshots for details).

   • For the comment or request_changes report type: Enable “Require a pull request before merging”, and in the submenu that pops up, additionally enable “Require conversation resolution before merging”. This makes sure that developers will have to resolve every comment added by the Axivion Suite before being able to merge the branch.

[1]

If your CI script outputs multiple AR files, you can just specify the --analysis_results_binary parameters multiple times.

8.2.2.3. Minimal workflow template

A minimal pipeline definition using the 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
         # CONFIGURATION 1: Output findings to local AR file.
         - name: Run Axivion CI
           id: axivion_ci
           run: ./.github/scripts/start_analysis.sh
         - name: Annotate PR with findings
           id: annotate_pr
           env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              GITHUB_REPOSITORY: ${{ github.repository }}
              GITHUB_PULL_REQUEST: ${{ github.event.number }}
              GITHUB_REPORT_TYPE: comment # can also be one of 'request_changes', 'warning', 'error'
           run: annotate_pr github --analysis_results_binary results.ar # change this to refer to your AR file(s)
         # CONFIGURATION 1 END

         # CONFIGURATION 2: Output findings to Dashboard.
         - name: Run Axivion CI
           id: axivion_ci
           run: |
              ./.github/scripts/start_analysis.sh
              # NOTE: Replace "PUT_NAME_HERE" with the right Dashboard project name.
              #       You can also do this within the `start_analysis.sh` script instead.
              echo "DASHBOARD_PROJECT_NAME=PUT_NAME_HERE" >> "$GITHUB_OUTPUT"
         - name: Annotate PR with findings
           id: annotate_pr
           env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              GITHUB_REPOSITORY: ${{ github.repository }}
              GITHUB_PULL_REQUEST: ${{ github.event.number }}
              GITHUB_REPORT_TYPE: comment # can also be one of 'request_changes', 'warning', 'error'
              DASHBOARD_URL: "https://..."  # replace this with the actual Axivion Dashboard URL.
              DASHBOARD_API_TOKEN: ${{ secrets.DASHBOARD_API_TOKEN }}
              DASHBOARD_PROJECT_NAME: ${{ steps.axivion_ci.DASHBOARD_PROJECT_NAME }}
           run: annotate_pr github
         # CONFIGURATION 2 END

Note

There are several more configuration parameters available for annotate_pr than are shown here. Run annotate_pr github --help to get an overview of them.

8.2.2.4. Screenshots

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

Status checks at the bottom of the PR. Here, the Axivion Suite check is failing due to some issues it found.

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.

Here (within the branch rulesets configuration), you can require the Axivion Suite to successfully run before a PR can be merged.