How do I run a self-hosted CI runner on a VPS?

Which runner software, and which version?

Use the agent of the forge that hosts your code; all three run on the Debian and Ubuntu images of every plan. The runner asks its forge for work over HTTPS; GitHub's stated network requirement is outbound HTTPS on port 443.

How do I install GitLab Runner with the Docker executor?

Install Docker Engine, then GitLab's package, then register with a runner authentication token. GitLab's documentation asks you to download its repository script and read it before running it. The token comes from the project or group settings when you create a runner, and starts with glrt-.

After registration, set concurrent in /etc/gitlab-runner/config.toml to the number of jobs the VPS should run at once, and give each job container a cpus and memory limit under [runners.docker]. Leave privileged off for code you do not fully trust: GitLab's Docker executor page says privileged mode disables container security mechanisms and exposes the host to privilege escalation.

# Docker Engine (Debian and Ubuntu package it as docker.io)
sudo apt install docker.io
# GitLab's repository script: read it before running it
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh
sudo apt install gitlab-runner
# RUNNER_TOKEN holds the glrt- token created in GitLab
sudo gitlab-runner register --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image debian:13 \
  --description "vps-runner"

How do I add a GitHub Actions self-hosted runner?

From the repository: Settings, Actions, Runners, New self-hosted runner, then Linux and x64. GitHub shows the download and config.sh commands for the current release; the registration token inside them expires after one hour. Run them as an ordinary user, not root, then install the runner as a systemd service.

The runner updates itself by default. Turn that off and GitHub stops queuing jobs to a runner not updated within 30 days of a new release. Jobs run directly on the VPS under the runner's user unless the workflow declares a container:. The --ephemeral option of config.sh limits a registration to one job.

./config.sh --url https://github.com/OWNER/REPO --token TOKEN_FROM_THE_RUNNERS_PAGE
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

How do I set up a Forgejo Runner?

Download the binary, check its signature, create a runner user, then register and start the daemon. Forgejo's documentation is blunt about what the agent does: it performs remote code execution. Jobs run in Docker, Podman or LXC containers that you install separately. Host mode needs none of them, and Forgejo warns that it gives no isolation at all: one job can wreck the machine.

Forgejo Runner has no default configuration path. Generate a file and pass it with -c every time the daemon starts.

export RUNNER_VERSION=13.2.1
export URL="https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-amd64"
wget -O forgejo-runner "$URL"
wget -O forgejo-runner.asc "$URL.asc"
gpg --keyserver hkps://keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify forgejo-runner.asc forgejo-runner
sudo install -m 0755 forgejo-runner /usr/local/bin/forgejo-runner
sudo useradd --create-home runner
# then, as the runner user, in /home/runner
forgejo-runner generate-config > /home/runner/runner-config.yml
forgejo-runner register
forgejo-runner daemon -c /home/runner/runner-config.yml

Who should be allowed to run code on the runner?

Only people you would give a shell on the VPS. A CI job is code that runs on your server. GitHub's security guide says self-hosted runners should almost never be used for public repositories, because anyone can open a pull request whose workflow runs on your machine. The same holds for GitLab and Forgejo projects that accept outside contributions.

The same guide warns that a runner not wiped between jobs can be persistently compromised by one bad job.

• Run jobs in containers, and keep the Docker socket out of untrusted jobs.
• Give test jobs no deployment secrets; deploy from a second runner on its own VPS.
• Use short-lived registrations, such as --ephemeral on GitHub, when you can rebuild the runner automatically.
• Lock down SSH on the runner like any server: keys, not passwords.

Which plan for how many parallel jobs?

Size by RAM per job first. GitHub's hosted Linux runner for private repositories has 2 CPU, 8 GB of RAM and 14 GB of SSD; for public repositories it has 4 CPU, 16 GB and 14 GB (GitHub documentation, read 3 November 2026). A job that fits on that machine needs the same memory on yours. The vCPU of every plan are shared: they are scheduled on physical cores that neighbouring VPS also use. The RAM and NVMe space of your plan are reserved for your VPS only. A build that keeps every vCPU busy for a long time shares cores with neighbors, so expect build times to vary more than on dedicated cores.

How do I keep the runner's disk from filling up?

Clean containers, volumes and images on a schedule. GitLab Runner installs a clear-docker-cache script and recommends running it from cron, for example once a week; it removes unused containers and volumes but not images. docker system prune removes unused containers, networks, images and build cache, and its until filter keeps the recent ones that make the next job faster.

No plan includes backups, so keep your own copy of anything that matters. A runner is cheap to rebuild: keep its configuration file and your install notes elsewhere, and let the caches go.

# containers and volumes left by GitLab jobs
/usr/share/gitlab-runner/clear-docker-cache
# images, networks and build cache unused for 3 days
docker system prune -af --filter "until=72h"