Prepare CI Runner

When to use it

To run your GitHub Actions or GitLab CI jobs on your own server instead of the providers' hosted machines. Run Install CI Dependencies first, and Install Docker if jobs run containers.

Choosing the options

Runners — choose at least one.

• GitHub Actions — creates a github-runner account and installs the current runner release in /opt/actions-runner.
• GitLab Runner — installs the gitlab-runner binary with its own gitlab-runner account and systemd service.

Let runner accounts use Docker — adds the runner accounts to the docker group, which container jobs need. Membership of that group is equivalent to root on the server, so keep this server for CI and do not run untrusted code on a server that holds anything else.

What it does on the server

• GitHub Actions: downloads the current runner release from GitHub, checks it against the SHA-256 digest GitHub publishes, unpacks it into /opt/actions-runner owned by github-runner, installs the libraries it needs with its own bin/installdependencies.sh, and confirms it starts. A runner already registered in /opt/actions-runner is left alone.
• GitLab Runner: downloads the binary from GitLab's download site, checks it against GitLab's published release checksums, installs it, creates the gitlab-runner account and its systemd service. A GitLab Runner installed from a package is kept.

The platform never asks for a registration token. A token lets anyone run jobs for your repository or organisation, and it has no reason to hold one.

After the run

Register the runner on the server with the token your provider shows you:

• GitHub: in the repository or organisation, open Settings → Actions → Runners → New self-hosted runner and copy the registration token. On the server, as github-runner, run ./config.sh in /opt/actions-runner; it asks for the repository or organisation URL and the token. Then, as root, in the same directory, install and start the service with ./svc.sh install github-runner and ./svc.sh start.
• GitLab: in the project or group, open Settings → CI/CD → Runners, create a runner and copy its authentication token. On the server, as root, run gitlab-runner register and paste the token when asked.

The run's final note repeats these steps.

Common problems

"GitHub's release information could not be read" — The server could not reach api.github.com, or GitHub rate-limited the request. The step is retried automatically; run it again later if it still fails.

"The download of … did not match the SHA-256 digest GitHub publishes for it." — The download was corrupted or altered. Nothing was installed; run again.

"Docker is not installed, so … was not given access to it." — Run Install Docker, then this playbook again.

"Runners are not published for …" — GitHub and GitLab publish runners for x86_64 and aarch64 servers.