Skip to main content
[ PIER ]

Gitea

A painless self-hosted Git service — like GitHub, but yours.

Service #git#repository#ci#devops#code

Gitea is a lightweight, self-hosted Git service written in Go. It looks and works like GitHub — repos, pull requests, issues, CI integration, code review, releases — but runs as a single binary or a 100MB Docker container. Used by individual developers, OSS projects, and enterprises that don't want their code on someone else's cloud.

Deploy with Pier

  1. 1 Open the Pier dashboard and click Add service.
  2. 2 Pick Gitea from the template list.
  3. 3 Choose the version, set a service name, and Pier provisions the container, storage, and ports automatically.
  4. 4 Attach a domain if you want HTTPS. Traefik auto-provisions the Let's Encrypt certificate.

What is Gitea?

Gitea is a community-developed, lightweight, self-hosted Git service. It looks and behaves like GitHub — repos, pull requests, issues, milestones, releases, code review with inline comments, branch protection — but runs as a single ~100 MB Docker container on a $5/month VPS. Originally forked from Gogs in 2016, it now has a thriving community and an enterprise-grade feature set that includes Actions (CI/CD), package registries, code mirroring, LDAP/OAuth/SSO integrations, and webhook support.

For individuals and teams that don’t want their code on someone else’s cloud — or are tired of paying per-seat fees — Gitea is the default choice. It scales from one developer with a private side-project repo to organizations with thousands of users and tens of thousands of repos.

How Pier deploys it

Pier uses the official gitea/gitea Docker image with /data mounted as the persistent volume — that holds the SQLite database (default backend), Git repositories, attachments, and configuration. Default port is 3000/tcp for HTTP. Pier auto-generates the initial admin password during setup.

For a heavier deployment with PostgreSQL backend, use the gitea-postgresql template — it provisions Gitea + a dedicated PostgreSQL container in one Docker Compose stack.

For HTTPS, attach a domain — Traefik handles cert issuance, and Gitea’s ROOT_URL is set automatically from the X-Forwarded-Host header.

When NOT to use Gitea

For full DevSecOps with vulnerability scanning, container scanning, and a built-in CI/CD pipeline visualization — GitLab CE is more complete (but much heavier). For email-driven minimalist workflows — sr.ht. For hobby/one-person projects — straight git over SSH on a server might be all you need.

Key features

GitHub-like UI

Web UI for repos, branches, PRs, issues, milestones, releases, wikis. If you've used GitHub, you already know Gitea.

Single binary, low resources

~100 MB Docker image, runs comfortably on a 1 GB VPS. SQLite, MySQL/MariaDB, or PostgreSQL backends — choose your storage.

Actions (CI/CD)

Gitea Actions is GitHub Actions-compatible — most actions/* and community actions just work. Run runners in containers via the gitea/act_runner image.

Code review & PRs

Pull requests with inline comments, review threads, required reviewers, merge strategies (merge / rebase / squash), branch protection, code owners.

Package registry

Built-in registries for npm, Maven, NuGet, PyPI, Cargo, Composer, RubyGems, Helm, Docker, Pub, Conan, Generic. Replace a separate Verdaccio/Nexus.

Multi-auth integrations

Local accounts, LDAP, SMTP, OAuth2 (Google, GitHub, GitLab, Discord, Azure AD, custom OIDC), SSPI, PAM. Auto-link via JIT provisioning.

Use cases

Private team Git server

Host your team's code without paying GitHub per-seat. Same features for ~$5/month VPS.

OSS project home

Host an OSS project (with issues, PRs, releases, Actions) on infrastructure you control. Mirror to GitHub for visibility.

Code mirroring

Pull mirror from GitHub/GitLab on schedule — keep an off-site copy of every dep your team relies on.

Package registry for internal artifacts

One server for code + npm + Maven + Docker images. No Verdaccio, no Nexus, no JFrog.

CI/CD for non-cloud workloads

Gitea Actions runs on your own runners — IoT/embedded targets, GPU boxes, air-gapped environments where GitHub-hosted runners can't reach.

Code examples

Push a new repo bash 
git remote add origin https://gitea.example.com/yourname/repo.git
git push -u origin main
Gitea Actions workflow yaml 
# .gitea/workflows/test.yaml
name: test
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
Publish to npm registry bash 
# ~/.npmrc
@yourorg:registry=https://gitea.example.com/api/packages/yourorg/npm/
//gitea.example.com/api/packages/yourorg/npm/:_authToken=<token>

npm publish
API — create a repo bash 
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","private":true}' \
  https://gitea.example.com/api/v1/user/repos

How it compares

vs GitHub GitHub is hosted, polished, $4-21/user/month for private repos. Gitea is OSS, self-hosted, free for unlimited users at the cost of a $5/month VPS. Feature parity is high; Gitea misses GitHub Copilot integration and some advanced enterprise features.
vs GitLab GitLab CE is feature-rich but heavy — RAM-hungry, complex setup. Gitea hits 80% of the features at 5% of the resource footprint. Pick GitLab for full DevSecOps; Gitea for a clean Git + CI + registry server.
vs Forgejo Forgejo is a community-friendly fork of Gitea (forked in 2022 over governance concerns). Same UI, same features, same codebase mostly. Pier ships Gitea; you can install Forgejo via a custom Docker template.
vs Sourcehut, Gogs Sourcehut (sr.ht) is email-driven minimalism — different paradigm. Gogs is the original project Gitea forked from in 2016 and is now less actively maintained.

Frequently asked questions

Which version does Pier deploy?
Default `latest` (Gitea 1.22+). Specific versions like `1.22` and `1.21` are pinned variants.
SQLite, MySQL, or Postgres for the backend?
For solo / small team — SQLite is fine and the simplest. For 10+ users or heavy use, run Postgres alongside (use the `gitea-postgresql` template which bundles both).
How do I run CI?
Gitea Actions is built-in but needs runners. Spawn the `gitea/act_runner` container, register it with a token, and Actions workflows fire automatically on push.
How does Pier handle HTTPS?
Attach a domain in Pier's Domains tab. Traefik issues a Let's Encrypt cert; Gitea's `ROOT_URL` is set to the domain automatically.
SSH access for git clone?
Gitea's SSH port (default 22, internal) needs to be either NATted via Traefik (which doesn't do raw TCP by default) or exposed at host level. Easiest — use HTTPS clone with personal access tokens.
How do I migrate from GitHub?
Gitea has a built-in importer for GitHub repos, including issues, PRs, comments, milestones, releases, and wikis. Settings → Migrations → Import from GitHub.
Backup strategy?
Two pieces — the SQLite/Postgres DB (Pier backs this up on schedule) and the `/data/git/repositories` directory (rsync the volume, or `gitea dump` for a full archive).

Related services

Deploy on your VPS

Gitea is a lightweight, self-hosted Git service written in Go. It looks and works like GitHub — repos, pull requests, issues, CI integration, code review, releases — but runs as a single binary or a 100MB Docker container. Used by individual developers, OSS projects, and enterprises that don't want their code on someone else's cloud.

Deploy this service →