Setting Up a Forgejo Actions Runner
Push-to-deploy with a self-hosted Forgejo Actions runner on the same VPS: own user, no Docker, narrow sudo rights and secrets kept in Forgejo.
Reviewed by adrian
on
After moving my Git repositories from GitHub to a self-hosted Forgejo instance, the next step was to move deployment off my laptop. Instead of running ./scripts/deploy.sh locally and hoping nothing was uncommitted, I wanted git push to trigger the build and roll out the container automatically.
The setup
- VPS: a single Debian machine hosting both Forgejo (rootless Podman container) and the website (
/opt/websites/adrian-altner.de, run by apodman-compose@systemd service). - Forgejo: v11 LTS, rootless, running under a dedicated
gitsystem user. - Goal: on every push to
main, rebuild the production image and restart the service, all on the same machine.
Why a dedicated runner user
The runner executes whatever code the workflow files define. Running it as the git user, which has access to Forgejo's database and every repository, would be a bad idea. I created a separate system user with its own home directory:
sudo useradd --system --create-home \
--home-dir /var/lib/forgejo-runner \
--shell /bin/bash forgejo-runner
That user gets no sudo by default. Further down, it gets targeted rights for exactly the commands the deploy needs.
Install the runner binary
The runner comes as a single static binary from Forgejo's own registry. I fetched the latest release with a script:
LATEST=$(curl -s https://code.forgejo.org/api/v1/repos/forgejo/runner/releases \
| grep -oE '"tag_name":"v[0-9.]+"' | head -1 | cut -d'"' -f4)
VER="${LATEST#v}"
cd /tmp
curl -L -o forgejo-runner \
"https://code.forgejo.org/forgejo/runner/releases/download/${LATEST}/forgejo-runner-${VER}-linux-amd64"
chmod +x forgejo-runner
sudo mv forgejo-runner /usr/local/bin/
forgejo-runner --version confirmed v12.9.0, the current major version, compatible with Forgejo v10, v11 and later.
Enable Actions in Forgejo
Actions are off by default. I added the minimal configuration to app.ini (inside the rootless container's volume at /home/git/forgejo-data/custom/conf/app.ini):
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://code.forgejo.org
DEFAULT_ACTIONS_URL matters because GitHub's Actions marketplace isn't reachable as it is. Forgejo keeps its own mirrors of common actions such as actions/checkout at code.forgejo.org/actions/*. After a container restart, the actions_artifacts storage directory showed up in the logs.
Register the runner
A runner can serve a single repository, a user account or the whole instance. I started with a registration for my website's repository, then moved it to my user account, so the same runner serves every repository I own without registering again.
The registration token comes from User Settings → Actions → Runners → Create new Runner:
sudo -iu forgejo-runner /usr/local/bin/forgejo-runner register \
--no-interactive \
--instance https://git.altner.cloud \
--token <REGISTRATION_TOKEN> \
--name arcturus-runner \
--labels "self-hosted:host"
The label self-hosted:host means "jobs labelled self-hosted run directly on the host". The runner itself needs no container runtime; Podman is already there for the application.
To move an existing runner from a repository to the user account, stop the service. Then delete the old runner in the Forgejo interface, remove /var/lib/forgejo-runner/.runner locally, get a new user-level token, register again, start the service. Same binary, different scope.
Running without Docker
On first start, the runner refused to run:
Error: daemon Docker Engine socket not found and docker_host config was invalid
Even with only the host label, the runner looks for a Docker socket on startup. The server only has rootless Podman, so I generated a config file and switched the Docker check off:
sudo -iu forgejo-runner /usr/local/bin/forgejo-runner generate-config \
> /tmp/runner-config.yaml
sudo mv /tmp/runner-config.yaml /var/lib/forgejo-runner/config.yaml
sudo chown forgejo-runner:forgejo-runner /var/lib/forgejo-runner/config.yaml
sudo -iu forgejo-runner sed -i \
-e 's|docker_host: .*|docker_host: "-"|' \
-e 's| labels: \[\]| labels: ["self-hosted:host"]|' \
/var/lib/forgejo-runner/config.yaml
Systemd service
[Unit]
Description=Forgejo Actions Runner
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=forgejo-runner
Group=forgejo-runner
WorkingDirectory=/var/lib/forgejo-runner
ExecStart=/usr/local/bin/forgejo-runner --config /var/lib/forgejo-runner/config.yaml daemon
Restart=on-failure
RestartSec=5s
NoNewPrivileges=false
ProtectSystem=full
ProtectHome=read-only
ReadWritePaths=/var/lib/forgejo-runner
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now forgejo-runner
Just enough sudo
The deploy step builds a Podman image and restarts the systemd service that runs it. Both need root. Instead of giving the runner user broad sudo, I wrote a narrow allowlist in /etc/sudoers.d/forgejo-runner-deploy:
forgejo-runner ALL=(root) NOPASSWD: /usr/bin/podman build *, \
/usr/bin/podman container prune *, \
/usr/bin/podman image prune *, \
/usr/bin/podman builder prune *, \
/usr/bin/systemctl restart [email protected], \
/usr/bin/rsync *
visudo -cf checks the syntax before you lock yourself out of sudo entirely.
The workflow
Workflows live under .forgejo/workflows/*.yml. The deploy does what my old shell script did, minus the SSH:
name: Deploy
on:
push:
branches: [main]
workflow_dispatch:
jobs:
deploy:
runs-on: self-hosted
env:
DEPLOY_DIR: /opt/websites/adrian-altner.de
steps:
- uses: actions/checkout@v4
- name: Sync to deploy directory
run: |
sudo rsync -a --delete \
--exclude='.env' \
--exclude='.env.production' \
--exclude='.git/' \
--exclude='node_modules/' \
./ "${DEPLOY_DIR}/"
- name: Build image
run: |
cd "${DEPLOY_DIR}"
sudo podman build \
--build-arg WEBMENTION_TOKEN="${{ secrets.WEBMENTION_TOKEN }}" \
-t localhost/adrian-altner.de:latest .
- name: Restart service
run: sudo systemctl restart [email protected]
- name: Prune
run: |
sudo podman container prune -f 2>/dev/null || true
sudo podman image prune --external -f 2>/dev/null || true
sudo podman image prune -f 2>/dev/null || true
sudo podman builder prune -af 2>/dev/null || true
Secrets stay in Forgejo
Anything sensitive, in my case the API tokens for webmention.io and webmention.app, lives in Settings → Actions → Secrets and reaches the job as ${{ secrets.NAME }}. Forgejo stores secrets encrypted, and the workflow logs mask their values. The tokens appear in exactly two places: the workflow file (committed, by name only) and Forgejo's encrypted store (never in the repository).
The build-time token goes into the container as an ARG, is used only during the build stage and isn't present in the final image. podman run --rm <image> env | grep -i webmention confirms it's gone.
The one gotcha: Node on the host
The first real workflow run failed straight away:
Cannot find: node in PATH
actions/checkout@v4 is a JavaScript action. On a runner with the host label it runs directly on the VPS and needs a Node interpreter in PATH. One apt install later the runner was happy:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo systemctl restart forgejo-runner
Result
From git push origin main to the end of the pipeline (checkout, rsync, Podman build, systemd restart, prune, Webmention pings) takes about 1 minute 15 seconds. No SSH keys to rotate, no laptop involved, no doubt about which version of the code is live.
The runner uses about 5 MB of RAM while idle and asks Forgejo for new jobs every two seconds.
Reusing the runner for new projects
Because the runner is registered for my user account, CI for a new repository takes three steps:
- Add a
.forgejo/workflows/deploy.ymlwithruns-on: self-hostedto the repository. - Add the project's secrets in the repository's Actions settings.
- If the project has its own systemd service, add a line for
systemctl restart <new-service>to/etc/sudoers.d/forgejo-runner-deploy. Nothing else on the server changes.
The one-time work (user account, binary, config, systemd unit, Node, sudoers) pays off with every further project.
Based on
-
Setting up a Forgejo Actions runner for self-hosted CI/CD
(
raw/2026/2026-04-22/setting-up-a-forgejo-actions-runner-for-self-hosted-ci-cd.md) [post]
Topic
- Self-Hosting Running services on a server you control instead of using a provider's hosted version, with the upkeep that comes with it.
Builds on
- Forgejo on Debian 13 with Rootless Podman Forgejo as a rootless Podman container under its own user: a Quadlet for systemd, Caddy in front, SSH on port 2222 and the problems I ran into.
Uses
- Forgejo Git forge to host yourself: repositories, users, SSH access and CI/CD with Forgejo Actions and self-hosted runners. Codeberg runs on it.
- Podman Container engine without a background daemon that runs rootless by default on Linux and uses the same commands on macOS and on a server.
Mentioned in
- Astro Client Islands under a Strict CSP Why Astro islands fail silently under script-src 'self', how I allowed the two hydration inlines by sha256 hash, and a deploy check for hash drift.