Self-Host Forgejo on Your VPS: Complete 2025 Guide

Forgejo was born in 2022 as a community fork of Gitea, driven by concerns about the project's governance. Its development is entirely community-led, MIT-licensed, with no dependency on a commercial entity. For teams wanting full control over their source code, CI/CD pipelines, and artifacts without relying on GitHub, GitLab, or Bitbucket, Forgejo is the lightest option available. The interface will feel familiar to any GitHub user, migration from Gitea is seamless, and GitHub Actions compatibility lowers the barrier to adoption.

Size your VPS according to your actual team size before deploying Forgejo. For 1–5 developers with a few dozen repositories, 1 vCPU and 1 GB RAM are sufficient; Forgejo at rest uses around 80 MB. For 5–20 developers with active CI/CD, plan for 2 vCPU and 2 GB RAM. Beyond 20 developers or for large repositories (monorepos, binaries), 4 vCPU and 4 GB RAM ensure a smooth experience. For storage, account for your Git repository volume plus 20% headroom for artifacts and backups.

On the network side, three ports must be open in your firewall: port 80 (HTTP, for Let's Encrypt validation), port 443 (HTTPS, web traffic), and port 2222 (Git SSH, to avoid conflicting with the admin SSH on port 22). On the software side, you need Docker Engine ≥ 24, Docker Compose v2, and a domain name pointing to your VPS.

Compatibility with GitHub Actions syntax is broad. Create .forgejo/workflows/ci.yml at the root of your repository:

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          npm ci
          npm test

The runs-on labels correspond to the labels declared when registering the runner. You can define multiple runners with different labels (e.g., arm64, gpu, high-memory) and target the right environment per job. Artifacts and caching work with the same official actions as on GitHub.

A freshly installed Forgejo is functional but not hardened. Here are the six points to address before opening the forge to your team.

Disable public registration. In *Site Administration → Settings → Users*, uncheck "Allow user registration". On an internal forge, nobody should be able to create an account without an invitation.

Enable 2FA for administrators. Every admin account must enable two-factor authentication under *Settings → Security*. Enforce 2FA for all users via the REQUIRE_SIGNIN_VIEW setting and organizational security policies.

SSH keys only. Disable password authentication in the host server's /etc/ssh/sshd_config (PasswordAuthentication no). For Git SSH (port 2222), Forgejo only accepts public keys registered in user profiles — this is its default behavior.

Webhook secrets. When creating each webhook (to external CI, Slack, etc.), always fill in the *Secret* field. Forgejo signs the payload with HMAC-SHA256; your receiver must verify this signature before processing the event.

Private packages. If you use the built-in package registry, set the default visibility to *Private* in organization settings. Access tokens for publishing should have minimal scope (packages:write only, never a global admin token).

Firewall. Close all ports except 80, 443, and 2222. Port 3000 (internal Forgejo) must never be exposed directly; it is consumed only by the reverse proxy on loopback.

The Docker update procedure is straightforward and requires only a few seconds of unavailability.

cd /opt/forgejo
# 1. Pull the new image
docker compose pull forgejo

# 2. Back up the database before any migration
docker compose exec db pg_dump -U forgejo forgejo > backup-$(date +%Y%m%d).sql

# 3. Restart the service
docker compose up -d forgejo

# 4. Verify schema migrations
docker compose logs forgejo | grep -i migrat

Forgejo runs its migrations automatically on startup. Verify that a Finished successfully line appears in the logs. In case of a migration error, restore the SQL backup and report the issue on the Forgejo tracker. Always read the release notes before jumping major versions — major version migrations may require an intermediate step.

SSH connection refused on port 2222. First verify the port is published by Docker (docker compose ps → Ports column). Then test from the client: ssh -p 2222 [email protected]. If the response is PTY allocation request failed, the connection is working — Forgejo responds Hi <user>! You've successfully authenticated. If you get Connection refused, the firewall is blocking the port: ufw allow 2222/tcp.

Runner showing offline in the interface. The runner contacts Forgejo over outbound HTTPS. Verify the runner container can resolve and reach git.yourdomain.com. A self-signed certificate requires mounting your CA in the container. Restart the runner after fixing connectivity: docker compose restart runner.

Push rejected by a pre-receive hook. Forgejo may reject a push if a branch protection rule is active (code review required, mandatory CI tests) or if a file size rule is exceeded. The git error message contains the details. For large binaries (> 100 MB), use Git LFS: Forgejo supports the LFS protocol natively.

Slow interface after several months. Run the Git garbage collector on active repositories from the admin panel: *Administration → Repositories → Git Repositories → Run Git GC*. To automate this, configure the scheduled task in app.ini under [cron.run_task].