8.2.3. Gitea Actions Integration

8.2.3.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.3.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 as a Gitea act runner. Ensure the Axivion Suite is installed and properly configured on this server so that all necessary tools (e.g., axivion_ci) are available. Refer to Gitea’s documentation on how to set up runners and add them to the repository for instructions (excluding the Axivion Suite installation).

    • In your configuration file, specifically in runner.labels, assign the label axivion:host to the runner. This ensures the runner is selected for Axivion jobs and that jobs run directly on the host machine (host executor) rather than within a Docker image.

  3. Add an annotate_pr rule to the PostCIActions section 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 script named start_analysis.sh to the .gitea/scripts/ directory (create it if it does not already exist). 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.

  5. In the same branch, add an empty file named axivion.yml to the .gitea/workflows/ directory (create it if it does not already exist).

  6. Enter your desired Gitea Actions workflow into this axivion.yml file. A recommended minimal template for running the analysis and annotating the pull request is available in Minimal workflow template. Gitea Actions is designed for compatibility with GitHub Actions; therefore, the GitHub documentation for syntax is available here. Differences from 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 time, you can view the progress of the CI workflow under the “Actions” 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.

  8. Finally, you may want to require that all findings be handled before a PR can be merged. To do this, configure your main branch as a protected branch and ensure “Enable Status Checks” is checked. Under “Status check patterns”, enter Axivion*. With this setting, pull requests can only be merged if no CI pipeline reports an error. To ensure the pipeline reports an error when issues are encountered (and thus blocks merges until they are resolved), set the following options in the rule configuration: * Set general_options.fail_if_issues_exist to True. * Set abort_on_error to True. * Ensure failure_exit_code is set to a non-zero value (which is the default).

8.2.3.3. Minimal workflow template

A minimal pipeline definition using the Axivion Suite with annotate_pr is shown below:

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 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. Running 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) is described in Generating review comments with annotate_pr.

8.2.3.4. Screenshots

The following screenshots demonstrate the integration in action.

Status check overview with pending Axivion Suite check

Status checks at the bottom of the PR. The branch cannot be merged yet because the Axivion Suite check is still pending.

A comment about a style violation posted by annotate_pr.

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

Setting up a protected branch to require Gitea Actions to pass.

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