2 Continuous integration

Vectornaut edited this page 2025-03-11 23:07:31 +00:00

Table of Contents

• Running continuous integration locally
• Motivation
• Setup
• Install Forgejo Runner
• *(Optional)* Install Docker and build the continuous integration container image
• Execution
• Running directly on your development system
• Running in a Docker container
• Running one particular job

Running continuous integration locally

Motivation

There are situations where you'll want to run the continuous integration workflow on a development machine. These include:

• You want to check whether your code will pass continuous integration without committing your work.
• You want to work on the continuous integration workflow.

Setup

Install Forgejo Runner

Setting up Forgejo Runner for local, manual use is simpler than setting it up for remote, automated use.

On OpenSUSE Tumbleweed, you can install the forgejo-runner package by calling

sudo zypper install forgejo-runner

On other systems, you may need to install manually.

1. Download these files from the release page:

   • The binary forgejo-runner-#.#.#-linux-amd64.
   • (Recommended) The signature forgejo-runner-#.#.#-linux-amd64.asc.

2. (Recommended) Verify the binary's authenticity by checking its signature.

   1. Import Forgejo's public signing key by calling

      gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
      

      If that doesn't work, you can download the key manually:
      1. Search in OpenPGP keyserver web interface for the fingerprint listed after --recv above.
      2. Download the key and call gpg --import on it.
   2. Check the signature by calling

      gpg --verify forgejo-runner-#.#.#-linux-amd64.asc forgejo-runner-#.#.#-linux-amd64
      

3. Give the binary permission to be executed by the user who owns it.

4. (Optional) For convenience, put the binary in your command search path. I like to do this by placing two symbolic links in ~/.local/bin, which is already on my search path:

   • A link called forgejo-runner-#.#.# that points to the location of the binary forgejo-runner-#.#.#-linux-amd64.
   • A link called forgejo-runner that points to forgejo-runner-#.#.#.

   Now I can launch a specific version of the runner by calling forgejo-runner-#.#.#, and I can launch my chosen default version by calling forgejo-runner.

(Optional) Install Docker and build the continuous integration container image

If you want to run the continuous integration workflow in a Docker container, like the remote CI system does, you'll need to install Docker and build the container image.

1. Install Docker
   • On Ubuntu 22.04, I used the docker-compose package, although docker.io might be enough.
2. Go to the tools/ci-image folder in the dyna3 repository and run the build script. The script tells Docker to build the image described by the neighboring Dockerfile and place it in Docker's image store with the tag dyna3:ci.

If you rebuild the Docker image with changes, the old version will still be sitting around in Docker's image store. Here's how to remove it.

• If you only ever ran the old version through Forgejo Runner, all the containers that referred to it should've been cleaned up automatically, so docker image prune should remove it.
  • ⚠️ This will also remove any other unreferenced images you might have in the image store.
• If you ever ran the old version some other way, there may still be a container referring to it. In this case, get the old image's ID by finding it in the list displayed by docker images. Calling docker image rm on that ID should lead to an error that mentions which containers refer to the old image. Use docker ps -a to examine those containers and confirm that they're not needed anymore. Then use docker rm to remove the containers that refer to the old image.

Execution

Running directly on your development system

1. Go into the top level of the dyna3 repository and call

   forgejo-runner exec --image -self-hosted
   

This will only work if your build system is set up in the way the continuous integration workflow expects. For example, it assumes that you can call Cargo with the command cargo.

Running in a Docker container

1. Go into the top level of the dyna3 repository and call

   forgejo-runner exec
   

This will only work if you've done the Docker section of the setup procedure.

Running one particular job

The continuous integration workflow includes several jobs. If you only want to run one of them:

1. Look up the name of the job you want to run. Job names can be found in two places that I know of:
   • Listed under jobs in the workflow description, .forgejo/workflows/continuous-integration.yaml.
   • In the [continuous-integration.yaml/JOB_NAME] annotations in the workflow's console output.
2. Call one of the execution commands above with the extra option --job JOB_NAME.