Deploying a custom CI runner for Salsa

Sometimes it is advantageous to host your own Salsa CI custom runner. For example, as of November 2024, the default Salsa CI runners have a hardcoded limit of 3 hours per job. But some packages take longer than 3 hours to build or test. With a custom runner you can set the timeout to be whatever you like.

1. Install the gitlab-runner package. Currently, the version in Debian is so outdated that it doesn't work with Salsa. However, Debian packages are provided by the upstream GitLab project.

2. GitLab Runner can use a variety of executors. These instruction are written for Docker, but others probably work as well. To use Docker, you need to first install the docker.io binary package.

3. Navigate to the Salsa repository at https://salsa.debian.org/<username>/<repository>/-/settings/ci_cd and expand the Runners section.

  1. Disable the instance runners if you don't want to use them.

  2. Click on the New project runner button.

  3. Check the Run untagged jobs button (this is easiest, but you are welcome to tag them if you need more control).

  4. Create the runner and copy the authentication token displayed on the screen (this token cannot be viewed in Salsa after leaving this screen).

4. Run gitlab-runner register, entering the authentication token when prompted. Then run gitlab-runner start to start the service.

5. Modify /etc/gitlab-runner/config.toml if desired. An example config is below. Docker should automatically download the debian:unstable image from the central Docker repository, but if not run docker run debian:unstable. 

concurrent = 8
check_interval = 0
connection_max_age = "15m0s"
shutdown_timeout = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "my-cool-name"
  url = "https://salsa.debian.org"
  id = 10254
  token = "authentication-token"
  token_obtained_at = 2024-11-21T04:34:02Z
  token_expires_at = 0001-01-01T00:00:00Z
  executor = "docker"
  output_limit = 8192
  [runners.docker]
    image = "debian:unstable"
    cpus = "4"
    cap_add = ["NET_ADMIN"]
    privileged = true

You should set concurrent and cpus to be whatever you prefer. autopkgtest requires cap_add = ["NET_ADMIN"] and privileged = true. output_limit sets the maximum size of the job log in kilobytes.

If you receive an error in Salsa CI that gbp cannot find any branches you may need to change Settings > CI/CD > General Pipelines > Git Strategy from Git Fetch to Git Clone.

Running nspawn-based containers

There is some historical information below, but it appears to be too outdated to work.

See https://salsa.debian.org/federico/gitlab-runner-nspawn/ or using nspawn-runner