What are we building?

By the end, your Forgejo has a registered, active runner that executes workflows from the .forgejo/workflows/ directory. We rely on Docker-in-Docker (DinD): the runner starts each CI job in its own, disposable container, cleanly isolated from the host. Concretely, by the end this runs:

• the Forgejo runner (code.forgejo.org/forgejo/runner:13.0.0), which asks Forgejo for jobs,
• a Docker-in-Docker sidecar (docker:29-dind) in which the jobs run isolated,
• an example repository with a workflow that runs actions/checkout on every push and starts a small action.

Forgejo Actions is largely compatible with GitHub Actions – the same workflow syntax, many marketplace actions work unchanged. So you can keep using existing knowledge directly, just on your own server. Tested with Forgejo 16.0.1 and Runner v13.0.0 on Debian 13 / Docker 29.

Prerequisites

• A running Forgejo server behind a reverse proxy, reachable under a public HTTPS domain (YOUR_DOMAIN). The public URL is important – more on that below.
• Docker on the same server (the runner and its DinD sidecar run as containers).
• Admin access to Forgejo to generate the registration token.

Actions has been enabled by default since Forgejo 1.21. If you’ve set it explicitly in your Forgejo Compose (recommended), it says there:

    environment:
      FORGEJO__actions__ENABLED: "true"

CI jobs are more resource-hungry than the plain Git server – builds need CPU and RAM. For running the runner alongside Forgejo we therefore recommend a bit more reserve; how much your specific setup needs is estimated by the server calculator.

Step by step

Step 1: Get the registration token

The runner has to register with Forgejo once. For that you need a registration token. The easiest way is via the web interface: log in as administrator and go to Administration settings → Actions → Runners. There you see all runners and, at the top right, the button Create registration token.

Alternatively via the command line directly in the Forgejo container:

docker exec -u git forgejo forgejo actions generate-runner-token

That outputs a long token – copy it, you need it once shortly.

Step 2: Write the runner Compose

Create a dedicated folder and change into it:

mkdir -p /opt/forgejo-runner && cd /opt/forgejo-runner

Create the compose.yaml:

services:
  docker:
    image: docker:29-dind
    container_name: fjr-docker
    privileged: true
    restart: unless-stopped
    environment:
      DOCKER_TLS_CERTDIR: /certs
    volumes:
      - dind_certs:/certs
      - runner_data:/data

  runner:
    image: code.forgejo.org/forgejo/runner:13.0.0
    container_name: fjr-runner
    restart: unless-stopped
    depends_on: [docker]
    environment:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_CERT_PATH: /certs/client
      DOCKER_TLS_VERIFY: "1"
    volumes:
      - dind_certs:/certs:ro
      - runner_data:/data
    working_dir: /data
    command: forgejo-runner daemon

volumes:
  dind_certs:
  runner_data:

The most important points:

• The DinD service is deliberately called docker. Its automatically generated TLS certificate is issued for exactly this name – if the service is called something else, the runner fails with “certificate is valid for docker, not …” (see “When things go wrong”).
• privileged: true is needed by DinD to run its own Docker engine. That’s the price of isolation; secure the runner server accordingly.
• The runner talks to the DinD via DOCKER_HOST: tcp://docker:2376 with TLS; it shares the client certificates via the dind_certs volume.
• The registration lands as a .runner file in the runner_data volume and thus survives restarts and updates.

Step 3: Start DinD and register the runner

First start only the DinD sidecar so it generates its certificates:

docker compose up -d docker

Now register the runner once. Replace YOUR_TOKEN with the token from step 1:

docker compose run --rm runner forgejo-runner register \
  --no-interactive \
  --instance https://YOUR_DOMAIN \
  --token YOUR_TOKEN \
  --name my-runner \
  --labels "docker:docker://node:24-bookworm"

On success the output ends with Runner registered successfully. (a warning that register is “deprecated” you can ignore – it works).

The label docker:docker://node:24-bookworm means: jobs with runs-on: docker are executed in a node:24-bookworm container (brings Node.js and the usual build tools). Node 24 is the currently active LTS line – Node 20 has been out of support since April 2026.

Step 4: Start the runner and check the status

Now start the whole stack:

docker compose up -d

Check that both containers are running:

docker compose ps

Take a look at the runner log – here you see whether the registration worked:

docker compose logs runner

You should see a line like declared successfully and [poller] launched – the runner now actively asks Forgejo for jobs. In the web interface under Administration settings → Actions → Runners, my-runner appears with a green status dot and the label docker (see screenshot above). If it’s Idle with a green dot, all is well: it’s connected and just waiting for work.

Step 5: Create the first workflow

Workflows live in the repository under .forgejo/workflows/. In any repo, create the file .forgejo/workflows/ci.yml:

name: CI
on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v7
      - run: echo "Commit $GITHUB_SHA is being tested"
      - run: node --version

Broken down:

• on: [push] – the workflow starts on every push.
• runs-on: docker – selects our runner via the label docker.
• actions/checkout@v7 – checks out the code (the same action as with GitHub; Forgejo loads it automatically from its action registry).
• The two run steps output the commit and the Node version – a minimal but real example you later replace with your actual build/test commands.

Commit and push the file. The push triggers the workflow immediately.

Step 6: Look at the run

In the repository, open the Actions tab. Your run appears there – after a few seconds with a green checkmark:

A click on the run opens the job view with the individual steps and their logs. Here you see how actions/checkout clones the repository and the commands run one after another:

The node --version step outputs v24.20.0 for us – the proof that the job really ran in the node:24-bookworm container. With that your CI/CD is in place: from now on you can test, build and deploy whatever you need in the run steps.

When things go wrong

Maintenance & backups

Updates. You update the runner and DinD like any Compose stack:

cd /opt/forgejo-runner
docker compose pull && docker compose up -d

Keep the runner roughly on par with your Forgejo version – a heavily outdated runner version can run into problems with new Forgejo features. Pin a specific version instead of latest as above so updates happen deliberately.

Backups. What’s worth backing up is above all the .runner file in the runner_data volume – it contains the registration. If it’s lost, the runner registers as a new runner on the next start (the old one stays as “offline” in the overview and can be deleted there). A total loss is no drama: you get a new token and register again. The DinD data (dind_certs, job caches) is ephemeral and does not need to be backed up.

Cleanup. The CI jobs create unused images and layers in DinD over time. Clean them up occasionally so the disk doesn’t fill up:

docker compose exec docker docker system prune -af

Security. The DinD runs privileged – treat the runner host like a security-critical system: only necessary ports open, no other sensitive services alongside, and CI only for repositories whose workflows you control. Whoever allows workflows from foreign forks should engage intensively with their risks beforehand.

What are we building?

By the end, Forgejo 16.0.3 runs as a single container behind your Traefik, reachable at https://YOUR_DOMAIN with an automatic Let’s Encrypt certificate. You create repositories via the web interface and clone/push them either over HTTPS or over SSH. As the database we use SQLite – for a personal or small-team Git server that’s easily enough and saves an additional database container. Forgejo is the community fork of Gitea and clearly on the rise in the self-hosting scene.

Why self-host at all? Your code, your issues and your project history then live exclusively on your server – no dependence on the terms, rate limits or acquisitions of an external provider, and full data sovereignty. Forgejo is no stripped-down toy: it can do almost everything you know from GitHub (see step 7), but stays lean enough for a small VPS.

Prerequisites

• A server with Debian 13 and running Docker (tested on a netcup VPS).
• A reverse proxy with Traefik (the proxy network and the resolver le from it are assumed) – Forgejo brings no own HTTPS, Traefik handles the encryption.
• A (sub)domain that points to your server via an A/AAAA record (YOUR_DOMAIN).
• For real backups: encrypted backups with Restic.

Forgejo is frugal and runs even on the smallest vServer. How much server your planned setup needs in total is estimated by the server calculator.

Step by step

Step 1: Create the Compose file

Create a folder for the stack and change into it:

mkdir -p /opt/forgejo && cd /opt/forgejo

Create the file compose.yaml. Replace YOUR_DOMAIN with your real domain:

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16.0.3
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO__server__DOMAIN: YOUR_DOMAIN
      FORGEJO__server__ROOT_URL: https://YOUR_DOMAIN/
      FORGEJO__server__SSH_DOMAIN: YOUR_DOMAIN
      FORGEJO__server__START_SSH_SERVER: "true"
      FORGEJO__server__SSH_PORT: "2222"
      FORGEJO__server__SSH_LISTEN_PORT: "2222"
      FORGEJO__service__DISABLE_REGISTRATION: "true"
      FORGEJO__database__DB_TYPE: sqlite3
    volumes:
      - forgejo_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "2222:2222"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:3000/api/healthz"]
      start_period: 30s
      start_interval: 2s
      interval: 30s
      timeout: 5s
      retries: 3
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.forgejo.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls.certresolver=le"
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"
    networks: [proxy]
volumes:
  forgejo_data: {}
networks:
  proxy:
    external: true

The most important points in detail:

• FORGEJO__… variables configure Forgejo directly via environment variables (section and key via double underscore). ROOT_URL must be exactly the public HTTPS address, otherwise clone links and redirects point nowhere.
• Git over SSH is handled by Forgejo’s built-in SSH server (START_SSH_SERVER=true) – so you don’t have to touch your host’s hardened SSH access (port 22). It listens on 2222 in the container and is published to the same host port.
• loadbalancer.server.port=3000 tells Traefik the web interface runs internally on port 3000. Only SSH (2222) is published directly as a port – web access goes exclusively via Traefik.
• The healthcheck with start_interval: 2s is deliberately set that way (more on that in “When things go wrong”).
• DISABLE_REGISTRATION: "true" closes open self-registration from the start – your Git server is thus not open to strangers. You still create your admin account perfectly normally in the initial install wizard (step 3); alternatively you could generate it automatically via FORGEJO__admin__* variables.

Step 2: Start and wait for “healthy”

Start the container:

docker compose up -d

Check the status:

docker compose ps

After a few seconds the container is healthy:

NAME      IMAGE                                 SERVICE   STATUS                    PORTS
forgejo   codeberg.org/forgejo/forgejo:16.0.3   forgejo   Up 12 seconds (healthy)   22/tcp, 3000/tcp, 0.0.0.0:2222->2222/tcp, [::]:2222->2222/tcp

The 22/tcp in the port list is only a port declared by the image, not a published one – the only port reachable from outside is the 2222 you mapped yourself.

Traefik now fetches the certificate in the background. Check from your machine that the web interface responds over HTTPS:

curl -s https://YOUR_DOMAIN/api/healthz

Expected output – Forgejo reports itself healthy. As long as the initial install (step 3) isn’t finished, the endpoint answers briefly with status and slogan:

{
  "status": "pass",
  "description": "Forgejo: Beyond coding. We forge."
}

Once the wizard is done, the same URL additionally lists the individual checks cache:ping and database:ping – and shows your instance name instead of the slogan.

Step 3: Initial install & admin account

Open https://YOUR_DOMAIN in the browser. On the first start, Forgejo shows the initial install. The database and server settings are already correctly pre-filled thanks to the environment variables – you only have to create the administrator account here (expand the corresponding section and enter a username, email and a strong password). A click on Install Forgejo, and after a brief restart you land on your empty dashboard:

Step 4: Create the first repository

Click the + at the top right and then New Repository. Assign a name and check Initialize repository (creates a README right away so the repo isn’t empty):

After creating it, you see the repository view. Via the HTTPS / SSH toggle you get the matching clone address:

Step 5: Clone and push over HTTPS

The fastest way is over HTTPS – it works immediately, without setting up keys:

git clone https://YOUR_DOMAIN/YOUR_USER/my-first-repo.git

A public repository clones without any login – expected output:

Cloning into 'my-first-repo'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (3/3), done.

For a private repository, Git asks for a username and password right here. That closes the loop – you create a file, commit it and push it back to your server:

cd my-first-repo
echo "My first note" >> notes.txt
git add notes.txt
git commit -m "First note"
git push

At the latest on git push, Forgejo wants to know who you are: Git asks for a username and password. At the end, Git confirms the new state on the server:

To https://YOUR_DOMAIN/YOUR_USER/my-first-repo.git
   f398f79..7bad57b  main -> main

Seconds later the commit appears in the web interface – your code now lives versioned on your own server.

Step 6: Clone and push over SSH

For daily use, SSH is more convenient (no password per push). For that, store your public SSH key under Settings → SSH / GPG keys → Add key:

You display your public key locally with cat ~/.ssh/id_ed25519.pub (if none exists yet: ssh-keygen -t ed25519). Then clone over SSH – note port 2222:

git clone ssh://git@YOUR_DOMAIN:2222/YOUR_USER/my-first-repo.git

For that to work, the SSH port must be open in both firewalls – in the UFW firewall (ufw allow 2222/tcp) and, if used, in the netcup firewall.

Step 7: More than just Git hosting

A repository and cloning are just the beginning – Forgejo brings the complete workbench around it. You find these features in the navigation bar of every repository or your account:

• Issues & pull requests: a full-featured ticket system and code review including labels, milestones and assignments – the basis for team collaboration.
• Forgejo Actions: a CI/CD engine compatible with GitHub Actions. Existing .github/workflows files often run unchanged. Actions do, however, need a separate runner that executes the jobs – for security reasons it doesn’t belong on the production host and has its own tutorial: Forgejo Actions: your own CI/CD runner with Docker (makes the case for dedicated cores: a good reason for a root server, see netcup recommendation).
• Wiki & releases: documentation right at the project and versioned release downloads.
• Package registry: Forgejo can host container images, npm, Maven, PyPI and other packages – handy if you want to store your own artifacts without running another service.
• Organizations & teams: bundle repositories and control access rights per team.

You also don’t have to migrate your projects by hand: via + → Migration, Forgejo imports an existing repository from GitHub, GitLab or another Forgejo/Gitea instance – including issues, pull requests and releases, not just the Git history. This way you switch from GitHub to your own server in a few minutes without losing anything.

When things go wrong

Maintenance & backups

Everything lives in the forgejo_data volume (/data): the SQLite database, your repositories and the SSH server’s host keys. This very volume is what should be backed up – cleanest with Restic. Because a SQLite file is written during operation, you back it up consistently by either briefly stopping the container (docker compose stop) or using Forgejo’s built-in dump:

docker compose exec -u git forgejo forgejo dump -t /tmp -f /tmp/forgejo-dump.zip

-u git runs the dump as the git user instead of root (as root, Forgejo refuses the dump). To /tmp instead of /data, because the git account can’t write in /data itself (the root directory /data belongs to root, only the subfolders like /data/gitea and /data/git belong to the git user) and the dump would otherwise write recursively into the packed data directory. You then fetch the finished zip out of the container – to where Restic backs it up:

docker compose cp forgejo:/tmp/forgejo-dump.zip ./forgejo-dump.zip

The zip contains the database dump (forgejo-db.sql), the app.ini and all repository data – a complete, self-contained restore point.

Updates: Forgejo releases new versions regularly (currently the 16 series). For an update, set the new tag in the compose.yaml (instead of 16.0.3) and pull it:

docker compose pull && docker compose up -d

Because the data lives in the volume, repos and accounts are preserved. Deliberately pin the version to a fixed tag instead of latest and take a look at the release notes before a major jump – any migration hints are there. Also make a fresh backup before every update: a Git server without a working backup is a concentrated risk for all your code.

Securing it: A publicly reachable Git server is a worthwhile target. Three things you should do right away: disable open registration (see step 3), enable two-factor authentication for your admin account under Settings → Security, and use a normal account instead of the administrator for everyday work. Keep Forgejo up to date promptly – the fast releases also contain security fixes. And publish only the ports you really need: outward, 443 (Traefik) and your SSH Git port 2222 suffice.