Gitea Runner

Search the Azure Marketplace for Gitea Runner on Ubuntu 24.04 LTS by SecureAnyCloud, choose Create, and complete the VM wizard.

Standard_B2s (2 vCPU, 4 GiB) is the recommended size and is enough for one job at a time. Choose a larger size if your builds are heavy.

Allow SSH (22) inbound and nothing else. A runner needs no inbound ports because it dials out to your Gitea instance. Port 22 is there only for you to administer the VM.

Accept the Marketplace image terms once per subscription, then create the VM. Run these commands on your own workstation, not on the VM.

az vm image terms accept --publisher sac --offer gitea-runner-ubuntu-24-04 --plan default
az group create --name gitea-runner-rg --location eastus
az vm create \
  --resource-group gitea-runner-rg \
  --name gitea-runner-vm \
  --image sac1647283583153:gitea-runner-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

SSH to the VM as azureuser:

ssh azureuser@<vm-public-ip>

The runner is installed and enabled, but it is deliberately not running. It has not yet been told where to connect.

gitea-runner --version docker version --format '{{.Server.Version}}' systemctl is-active docker gitea-runner-egress-filter systemctl is-enabled gitea-runner.service systemctl is-active gitea-runner.service || echo "(inactive is the correct state until the runner is connected)"

gitea-runner.service reporting inactive while is-enabled reports enabled is the correct state for a runner that is not connected yet. It is not a fault. The service has a condition on the registration file, so systemd skips it until that file exists.

One container image is present, so a workflow can run immediately, even on a VM with no outbound registry access:

docker image ls

List the listening sockets:

sudo ss -Hltn | awk '{print $4}' | sort -u

Off the VM, only SSH is listening. Everything else is bound to the loopback interface. The bundled checker asserts that exact set, rather than looking for a few unwanted ports:

sudo /usr/local/sbin/gitea-runner-port-check.sh

This check confirms that the image is connected to nothing: no registration file, no runner token and no remembered instance address.

sudo /usr/local/sbin/gitea-runner-registration-assert.sh

Every VM from this image generates its own runner name on first boot. Two runners registered to one Gitea instance must not share a name, so a second VM you deploy never collides with the first. Print the identity file:

sudo grep -vE '^#' /root/gitea-runner-credentials.txt

That file is 0600 root:root and holds no secret. The appliance has no credential of its own until you connect it to your instance.

NAME="$(sudo grep '^GITEA_RUNNER_NAME=' /root/gitea-runner-credentials.txt | cut -d= -f2-)" echo "This VM will register as: ${NAME}" echo "Recorded for this VM: <GITEA_RUNNER_NAME> at <GITEA_RUNNER_HOST>"

A registration token is a short-lived value that the runner exchanges, once, for its own long-lived token. Create one at the scope you want this runner to serve:

• Every repository on the instance: Site Administration > Actions > Runners > Create new runner
• One organization: Organization Settings > Actions > Runners
• One repository: Repository Settings > Actions > Runners

Copy the token. Also note the root URL of your instance, such as https://gitea.example.com/. Do not use the URL of a repository.

Write the instance URL and the token to /etc/gitea-runner/registration.env, then start the registration service:

sudo tee /etc/gitea-runner/registration.env >/dev/null <<'EOF' GITEA_INSTANCE_URL=https://<your-domain>/ GITEA_RUNNER_REGISTRATION_TOKEN=<your-token> EOF
sudo chmod 0600 /etc/gitea-runner/registration.env
sudo systemctl start gitea-runner-register

Registration writes /var/lib/gitea-runner/.runner, removes the spent registration token from registration.env and starts the runner. Confirm that it connected:

systemctl is-active gitea-runner.service || echo "(not connected yet — complete the block above first)"
sudo journalctl -u gitea-runner.service -n 20 --no-pager

A line reading declare successfully means the instance has accepted this runner. The runner now appears under Runners in your Gitea settings, with the name from Step 6 and the labels from Step 11.

To have the runner connect on its very first boot, supply the same two keys as custom data when you create the VM, in the same KEY=VALUE form. Custom data is readable by anything on the VM that can query the Azure instance metadata service. If that matters to you, leave it out at launch and write the token in afterwards.

In any repository the runner serves, commit .gitea/workflows/hello.yml:

name: hello on: [push] jobs: hello: runs-on: alpine-3.22 steps: - run: echo "Hello from $(hostname)" - run: cat /etc/os-release | head -2

Push it. The run appears under the repository's Actions tab, and the runner claims it within a couple of seconds.

runs-on: alpine-3.22 selects the image that ships with this VM, so this first workflow needs no registry access. runs-on: ubuntu-latest also works and is what most existing workflows use. It pulls the full Gitea runner image on first use, which takes a few minutes once and is then cached.

A runner executes code from anyone who can push to the repositories it serves, so it matters what a job can and cannot do. This probe runs a real workflow in a real container and reports back:

sudo /usr/local/sbin/gitea-runner-job-probe.sh

The probe asserts three things by running them, not by reading configuration:

• The job produced its own output.
• The job container had no Docker socket, so a workflow step cannot create containers of its own or take over the host.
• The job could not reach the Azure instance metadata service, which is where a VM's managed identity credentials are handed out.

Firewall rules, applied to container traffic only, enforce the last of these:

sudo iptables -S DOCKER-USER | grep REJECT
sudo /usr/local/sbin/gitea-runner-egress-filter.sh check

The rules refuse 169.254.169.254 outright and refuse the Azure agent's HTTP ports on 168.63.129.16. DNS to that address stays open on purpose. On Azure the platform DNS resolver is the same host, so blocking it entirely would leave every job unable to resolve anything.

To check the whole security posture in one command, run:

sudo /usr/local/sbin/gitea-runner-verify.sh

A label maps a runs-on: value to the container image that the job runs in. The shipped set is in /etc/gitea-runner/config.yaml:

grep -A5 '^ labels:' /etc/gitea-runner/config.yaml

To change the set, edit that list and re-register the runner. Alternatively, pass GITEA_RUNNER_LABELS in registration.env before you register. Labels take the form name:docker://image.

This image refuses a label ending in :host. Upstream supports such a label, which runs workflow steps directly on the VM instead of inside a container. That would void every isolation property described in Step 10. If you genuinely need host execution, this is not the right image.

Jobs run one at a time (capacity: 1 in the config), which suits Standard_B2s. On a larger VM, raise the value to run jobs in parallel.

actions/cache works out of the box. While the runner is running, it starts a cache server on port 8088. A firewall rule allows that port only from the Docker address pool, so job containers can reach it and nothing off the VM can:

sudo iptables -S INPUT | grep 8088

Cached data lives under /var/lib/gitea-runner.

The runner refuses to re-register somewhere new silently. Otherwise your first instance would keep listing a runner that this VM had quietly stopped serving. To move the runner deliberately:

• Delete the runner on the old instance's Actions > Runners page.
• On the VM, stop the service and remove the registration:

sudo systemctl stop gitea-runner.service
sudo rm -f /var/lib/gitea-runner/.runner

• Repeat Step 8 with the new instance URL and a token from that instance.

The OS and Docker update through Ubuntu's normal unattended upgrades. This includes the container engine, because the image uses the archive docker.io package rather than a third-party repository that unattended upgrades would not cover.

To upgrade the runner itself, replace the binary with a newer release from gitea.com/gitea/runner, then restart:

sudo systemctl restart gitea-runner.service gitea-runner --version

Check the release notes before you upgrade across a major version. A runner must be compatible with the Gitea instance it is registered to.