Gitea guide

What Gitea does in production

Gitea is an open-source Git hosting platform you operate yourself. Developers push code over HTTPS or SSH; Gitea stores repos, serves the web UI, manages users and orgs, and can run Gitea Actions — workflow YAML similar to GitHub Actions — on self-hosted runners. It often sits next to Jenkins, container registries like Harbor, and deploy targets such as Kubernetes.

Core pieces

Gitea server — HTTP(S) UI/API, Git smart HTTP, optional SSH
Database — SQLite (small), PostgreSQL or MySQL/MariaDB (production)
Data directory — repos, attachments, LFS, Actions artifacts (often /var/lib/gitea)
Config — app.ini (paths, DB, ROOT_URL, SSH, Actions)
Act runners — agents that execute Actions jobs (separate process/container)

Git access: HTTPS and SSH

Clone URLs look like https://gitea.example.com/org/repo.git or git@gitea.example.com:org/repo.git. HTTPS uses username + password or a personal access token; SSH uses keys registered in the user settings. Behind a reverse proxy, ROOT_URL and proxy headers must match the public URL or redirects and clone links break. See the Git lab and SSH lab for client-side failures.

Gitea Actions (CI/CD)

Enable Actions in app.ini and register one or more act_runner instances with a registration token from the UI (site admin, org, or repo). Workflows live under .gitea/workflows/ (the Gitea-native path) or .github/workflows/ (supported for compatibility with GitHub Actions repositories) — YAML syntax closely mirrors GitHub Actions. Jobs need a matching runner label (runs-on:). Secrets are stored in Gitea and injected at runtime — never commit them.

Minimal workflow

name: CI
on:
  push:
    branches: [main]
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: make test

How a push flows

Client — git push over HTTPS or SSH to Gitea
Receive — Gitea updates the bare repo under the data directory
Hooks / webhooks — optional notify Jenkins, Discord, etc.
Actions — matching workflows enqueue; runners pick jobs
Status — check appears on commit/PR in the UI

Webhooks and integrations

Repo or org webhooks POST JSON on push, PR, and other events. Failures show in webhook delivery history (non-2xx, TLS errors, wrong URL). CI systems often use webhooks instead of polling. For package registries and container images, Gitea can host packages or push outward to Harbor/Docker Hub from Actions.

Key paths and service

Config — /etc/gitea/app.ini (or custom path)
Data — APP_DATA_PATH (repos, LFS, Actions)
Logs — configured under [log] or journald
Service — gitea systemd unit, or Docker Compose stack
Default HTTP — often port 3000 behind nginx/Caddy/Traefik

Learning resources

Gitea documentation — docs.gitea.com
Gitea Actions — Actions overview
Configuration cheat sheet — app.ini reference
act_runner — Registering runners

Practice scenarios

Hands-on Gitea scenarios on live Linux VMs: gitea

Troubleshooting →