Host Gitea on your own VPS in 2026

Gitea uses barely 200 to 300 MB of RAM at idle, making it one of the most efficient Git forges to self-host. On a VPS, you keep full control of your source code: no data is analyzed by a third party, no arbitrary limit on the number of private repositories or collaborators, and no cost that climbs with your team. For an agency or an independent developer, a single VPS can host all client projects with permissions partitioned by organization. Gitea natively includes CI/CD compatible with GitHub Actions workflows (Gitea Actions), a package registry and a web editor, which covers almost the entire development cycle with no external dependency.

Gitea is very frugal. For a small team (up to 20 users), a VPS with 2 vCPU and 2 GB of RAM is more than enough; count on 4 GB if you enable Gitea Actions with local runners that compile code. Plan for at least 20 to 40 GB of SSD storage depending on the size of your repositories. On the software side: Docker Engine and the Docker Compose plugin installed, a domain name (or a subdomain such as git.yourdomain.com) pointing to the VPS IP via an A record, and port 22 reserved for the server's SSH — Gitea will expose its own SSH on another port to avoid the conflict.

Gitea Actions is Gitea's native CI/CD engine, compatible with GitHub Actions workflow syntax. It lets you run pipelines directly on your infrastructure, with no dependency on an external service.

To enable it, add to your app.ini:

[actions]
ENABLED = true

Then register an act_runner runner in a separate container on the same VPS. Cap its RAM via mem_limit so that a heavy build does not choke Gitea itself. For heavy pipelines (compilation, integration tests), dedicate a second VPS to the runner instead.

A minimal workflow for a Node.js project goes in .gitea/workflows/ci.yml:

on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm test

The runner executes this workflow on every push. You can combine multiple jobs, use version matrices, and share artifacts between steps — exactly like GitHub Actions, but on your own server.

Once Gitea is in production, a few maintenance operations come up regularly.

Managing webhooks. Gitea logs the history of every delivery in "Repository Settings → Webhooks → Recent Deliveries". A failed webhook (timeout, HTTP 5xx error) can be replayed manually from that history. If your runners run on the same private network as Gitea, add their IP ranges to ALLOWED_HOST_LIST in the [webhook] section of app.ini — otherwise calls to localhost are blocked by default since Gitea 1.20.

Purging orphaned repositories. A repository deleted through the interface leaves its Git data (objects/) on disk until the next background task run. Force an immediate pass from the admin: "Site Administration → Background Tasks → Run: Purge Deleted Repositories". The freed space only becomes visible after docker exec -u git gitea gitea admin storage --remove-unlisted.

Storage quota per organization. For multi-tenant instances, set a repository quota per organization in app.ini under [repository]: MAX_CREATION_LIMIT = 50. This prevents an account from creating hundreds of repositories unmonitored and filling the data volume.

Permission denied (publickey) after an upgrade. The binary referenced in authorized_keys has changed path (verified in 1.27). The Gitea service responds normally over HTTPS, which masks the problem. Fix with: docker exec -u git gitea gitea admin regenerate keys. Verify that a git clone over SSH succeeds before declaring the upgrade complete.

Timeout or SSL error during HTTPS clone. Three common causes: the ROOT_URL in app.ini does not match the actual HTTPS domain (broken links + possible redirect loop), the reverse proxy does not forward the X-Forwarded-Proto: https header (Gitea then generates HTTP URLs), or the Let's Encrypt certificate has expired (Caddy and certbot renew it automatically, but only if DNS still points to the VPS). Check ROOT_URL first: it is the most common cause after a domain migration.

Slow or stalling SSH clone. The SSH upload-pack uses the same Git process as web operations. If your act_runner is using all available CPU cores during a build, Git operations may end up waiting for CPU. Add cpus: '1.5' to the runner in the compose to reserve cores without starving it completely.

Database migration failed: column already exists. The database received a partial migration (stopped mid-upgrade). Restore the dump taken before the upgrade, start from a clean volume, then restart.

Version 1.27 changes the internal path of the gitea binary referenced inside authorized_keys. During the upgrade, existing entries still point to the old path: any clone or push over SSH silently fails with Permission denied (publickey), without any server-side error message pointing to the upgrade. The Gitea service responds normally over HTTPS, which masks the problem. After every upgrade to 1.27 (or to any version that changes this path), run inside the container: docker exec -u git gitea gitea admin regenerate keys. The command rewrites all authorized_keys entries with the correct binary path. Verify that a git clone over SSH succeeds before declaring the upgrade complete.

If you want to push automation around your Git forge further, the article Host Forgejo on your VPS covers setting up a Forgejo instance with dedicated Actions runners, configuring the built-in OCI registry, and security hardening (fail2ban, IP range restrictions). For teams wanting a complete continuous deployment pipeline, it is the natural complement to this guide.