8.2.2. Gitea Actions Integration

8.2.2.1. Background

• You have a running Axivion Suite configuration.

• Additionally, you want to integrate Axivion findings into Gitea pull requests via Gitea Actions.

8.2.2.2. What needs to be done?

1. Enable Gitea Actions for your repository by navigating to Settings -> “Enable Repository Actions”.

2. Set up at least one server to function as a Gitea act runner. On this server, the Axivion Suite should be installed and properly configured, such that all necessary tools (e.g., axivion_ci) are available. You can follow Gitea’s documentation on how to set up runners and add them to the repository for this (except for setting up the Axivion Suite).

   • In your configuration file, specifically in runner.labels, make sure that you assign the label axivion:host to the runner. This sets up the runner to be picked up for Axivion jobs, and it causes the jobs to be run on the machine itself (host executor) rather than in a Docker image.

3. Add an annotate_pr rule to the PostCIActions of your configuration. For Gitea, this is the AnnotateGiteaPR rule. Here, you configure how findings are reported. In particular, you should:

   • Set the report_type (comment or request_changes).

   • If you are not using the default gitea.com server, replace the server value with $(GITEA_SERVER). The actual URL will then be substituted during the CI run. Alternatively, set the server value to your server’s URL directly.

4. In a new branch of your repository, add a new script called start_analysis.sh to the .gitea/scripts/ directory (which you have to create if it doesn’t exist yet). This script should call axivion_ci. Thanks to the rule you added in the previous step, the same run will also annotate the pull request with any findings.

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

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

6. Enter your desired Gitea Actions workflow into this axivion.yml file. A recommended minimal template to run the analysis (which then also annotates the pull request) is available below, in Minimal workflow template. Gitea Actions is designed to be compatible with GitHub Actions, so the recommended documentation for the syntax, coming from GitHub, is available here. Differences to GitHub Actions are listed here.

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

7. 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 “Actions” 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.

8. Finally, you might want to enforce that all findings must be handled before allowing a PR to be merged. If you do, set up your main branch as a protected branch, and ensure “Enable Status Checks” is checked. Under “Status check patterns”, enter Axivion*. With this set, pull requests can only be merged if no CI pipeline reports an error. To ensure that the pipeline reports an error when it encounters any issues (and hence block merges before all issues are resolved), set the following options within the rule configuration: * fail_if_issues_exist needs to be set to True. * abort_on_error needs to be set to True. * Make sure that failure_exit_code is set to a non-zero value (this is the default).

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: axivion
      permissions:
         contents: read
         issues: write # To add comments
         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: ${{ !gitea.event.pull_request.draft && (gitea.event.pull_request.state != 'closed' || gitea.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 AnnotateGiteaPR rule, annotates the PR with any findings.
         - name: Run Axivion CI
           env:
              GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
              GITEA_REPOSITORY: ${{ gitea.repository }}
              GITEA_PULL_REQUEST: ${{ gitea.event.pull_request.number }}
              GITEA_SERVER: ${{ gitea.server_url }}
           run: ./.gitea/scripts/start_analysis.sh

Note

The AnnotateGiteaPR 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 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.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 branch cannot be merged yet, because the Axivion Suite check is still pending.

A comment shown on the PR overview tab. These types of comments are also included in the diff (“Files changed”) tab.

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