Every homelab reaches the same tedious moment: you SSH into a server, run a git pull, restart a Docker Compose stack, and realize you’ve done it five times this week. The steps never change, which makes them ideal for automation, and you don’t need an external CI service or a cloud account to do it.
If you already self-host Gitea, the automation engine is built in. Gitea Actions reads workflow files from your repository, and a small service called act_runner executes them on your own hardware. The syntax is largely compatible with GitHub Actions, so existing workflow knowledge carries over. This guide covers registering a runner with Docker Compose, writing a first deployment workflow, and the security trade-offs that matter on a home network.

Register an act_runner with Docker Compose
You need Gitea 1.21 or newer, where Actions is enabled by default. On an older install, or one where it was switched off, add an [actions] section with ENABLED = true to your app.ini and restart Gitea. Then open Site Administration, go to Actions, then Runners, and create a new runner to get a registration token. Organization and repository settings offer the same option, and a narrower scope is usually the better choice because it limits which projects can use the runner.
The runner itself ships as the gitea/act_runner image. Create a compose file with a single service, mount the Docker socket and a data volume, and pass the registration details as environment variables:
- GITEA_INSTANCE_URL: the address of your Gitea server, which must be reachable from inside the container, so “localhost” will not work
- GITEA_RUNNER_REGISTRATION_TOKEN: the token you just generated
- GITEA_RUNNER_NAME: any label that helps you recognize the machine later
- GITEA_RUNNER_LABELS: the job types this runner accepts, such as ubuntu-latest:docker://node:20-bullseye
- /var/run/docker.sock and /data: the socket lets jobs spawn containers, and the data volume keeps the runner’s registration across restarts
Labels deserve a moment of attention. A workflow asks for a runner with runs-on, and Gitea matches that value against the labels each runner advertises. The part after “docker://” is the container image used to run the job, so you choose the toolchain your builds get. Start the stack with docker compose up -d, refresh the Runners page, and the new entry should show as idle within seconds. If it shows offline instead, the cause is almost always the instance URL or a reverse proxy blocking the connection.
Write a workflow that deploys
Workflows live in a .gitea/workflows folder at the root of the repository. Create a file called deploy.yaml, trigger it on pushes to the main branch, set runs-on to ubuntu-latest, and add two steps: check out the code, then connect to the target machine over SSH.
Store the private key and hostname under the repository’s Actions secrets, never in the YAML file. The SSH step changes into the stack directory, pulls the latest commit, then runs docker compose pull followed by docker compose up -d. Make sure the job image includes an SSH client, since slimmer images often leave it out. Use a dedicated key for this one purpose, restricted to a low-privilege user on the target.

Where homelab runners get risky
Mounting the Docker socket into the runner is convenient and also dangerous. Anything with access to that socket can start a privileged container and effectively become root on the host. That is fine when you are the only person who can push to your repositories, but it becomes a real exposure if you invite collaborators or enable open registration. Keep the runner scoped to private repositories you control, and treat any workflow file as code that will run with serious privileges.
There are two ways to run jobs, and they suit different situations. Container mode, the default, gives every job a clean throwaway environment, which keeps builds reproducible and stops one job from polluting the next. Host mode runs the job directly on the machine, which you enable with a label such as homelab:host. Host mode makes sense when the deployment target is the same box as the runner, because you can skip SSH entirely and call Docker Compose directly. The cost is that the job has the full permissions of the runner’s user, so create a dedicated account that belongs only to the groups it needs.

Reliability needs planning too. Pin your job images to specific tags instead of “latest”, so a surprise upstream change doesn’t break deployments on a quiet Sunday. Remember that if the runner machine goes down, queued jobs simply wait, so a deployment pipeline is only as available as the host beneath it. Your Gitea data and runner volume also deserve a place in your backup routine, and a Restic and Backblaze B2 setup covers that cleanly.
One setting catches almost everyone: act_runner defaults to running a single job at a time. Generate a config file with act_runner generate-config, raise the capacity value under the runner section, and mount that file into the container. Otherwise a slow image build will sit in front of your quick deploy job, and you’ll spend an afternoon wondering why nothing is moving.





