Skip to content

Gitea

What it is

Gitea is a community-managed lightweight code hosting solution written in Go. It provides a complete Git service including repository management, issue tracking, code review, and CI/CD integration, with a focus on simplicity and high performance. It is a painless self-hosted Git service that serves as the backbone for private DevOps ecosystems in the July 2026 era, featuring native support for the Model Context Protocol (MCP) for agentic integration.

What problem it solves

It allows developers and home lab enthusiasts to host their own private Git repositories without the resource overhead of GitLab or the privacy concerns of public cloud providers like GitHub. In 2026, it specifically addresses the need for local, air-gapped code storage for proprietary AI training datasets and sensitive automation scripts that utilize Gemma 3 and Claude 4.8. It provides a central hub for code collaboration and automation that can run on low-power hardware.

Where it fits in the stack

Gitea sits in the Development & DevOps layer. It serves as the primary source of truth for code, configuration files, and automation workflows. It is the central registry for local GitOps, often triggering pipelines that deploy services across the entire homelab stack. It integrates with the MCP 3.0 Task Protocol to allow AI agents to manage repositories, issues, and pull requests autonomously.

Typical use cases

  • Private Code Hosting: Maintaining internal tools and projects away from public eyes.
  • GitOps: Storing infrastructure-as-code (Ansible, Terraform, K3s manifests) and triggering deployments.
  • AI Dataset Management: Hosting versioned datasets for fine-tuning local models like Gemma 3.
  • Local CI/CD: Running Gitea Actions for automated testing and deployment.
  • Documentation: Hosting project documentation via Gitea's built-in wiki or Markdown support.
  • Mirrors: Maintaining local mirrors of critical public repositories for offline access.
  • SSO Integration: Using OIDC for centralized authentication via Authentik.

Strengths

  • Performance: Extremely lightweight and fast; runs comfortably on a Raspberry Pi 5 or low-power NAS.
  • GitHub-Like UX: Familiar interface that requires minimal learning for existing Git users.
  • Built-in CI/CD: Gitea Actions provides high compatibility with GitHub Actions workflows, including concurrency support and reusable workflows from private repositories.
  • v1.26+ Features: Keyboard shortcuts (e.g., s for search), subpath archives, Vite-based front-end toolchain, Terraform registry/state backend support, and automatic release notes generation.
  • Self-Contained: Can be run as a single binary or a small Docker container with minimal dependencies.
  • Enterprise Ready: Supports OIDC, LDAP, and advanced repository mirroring.

Limitations

  • Ecosystem: Smaller plugin and integration ecosystem compared to GitHub or GitLab.
  • Scaling: Lacks the massive horizontal scaling capabilities (like GitLab Geo) for multi-region global teams.
  • Native AI Features: While it supports local LLM integration via Actions, it lacks the deeply integrated, first-party AI coding assistants found in GitHub (Copilot).

When to use it

  • When you want a lightweight, self-hosted alternative to GitHub or GitLab.
  • For managing GitOps workflows on home lab infrastructure with low resource overhead.
  • To maintain private copies of code and configuration without cloud dependencies.
  • When running Git services on edge devices or low-resource hardware like a NAS.

When not to use it

  • If you require advanced enterprise features like geo-replication or deep compliance auditing found in GitLab.
  • When you need the massive social ecosystem and public visibility of GitHub.
  • If your team relies heavily on proprietary third-party integrations that only support GitHub/GitLab APIs specifically.

Getting started

Docker Compose

To run Gitea using Docker Compose:

services:
  server:
    image: gitea/gitea:1.26.2
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

SSO & OIDC Integration (Authentik)

  1. Navigate to Site Administration > Authentication Sources > Add Authentication Source.
  2. Set Authentication Type to OpenID Connect.
  3. Configure the following:
    • Authentication Name: authentik
    • OAuth2 Provider: OpenID Connect
    • Client ID (Key): <Your Client ID>
    • Client Secret: <Your Client Secret>
    • OpenID Connect Auto Discovery URL: https://authentik.example.com/application/o/gitea/.well-known/openid-configuration
    • Additional Scopes: email profile

Enabling Gitea Actions

  1. In your app.ini, ensure Actions are enabled: 
    [actions]
ENABLED = true
  2. Set up a Runner: Gitea Actions requires a separate "Gitea Runner" (formerly act_runner).
  3. Registration: Registration tokens are managed via the administrative UI or CLI.

CLI examples

The gitea binary inside the container can be used for administrative tasks:

# Create an admin user
docker exec -u 1000 -it gitea gitea admin user create --username admin --password secret --email admin@example.com --admin

# Dump database and configuration for backup
docker exec -u 1000 -it gitea gitea dump

# List all repositories on the instance
docker exec -u 1000 -it gitea gitea admin repo list

API examples

Gitea features a comprehensive Swagger-documented API:

# Get repository information
curl -X GET "http://localhost:3000/api/v1/repos/owner/repo" \
  -H "Authorization: token <YOUR_TOKEN>"

# Create a new issue via API
curl -X POST "http://localhost:3000/api/v1/repos/owner/repo/issues" \
  -H "Authorization: token <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug Report", "body": "Observed in July 2026 build."}'

# Automated Code Review Pattern (Ollama Integration)
# Trigger a local LLM to review a pull request
CODE_DIFF=$(git diff origin/main)
PAYLOAD=$(jq -n --arg diff "$CODE_DIFF" '{
  model: "gemma3",
  prompt: ("Review this diff and suggest improvements:\n\n" + $diff),
  stream: false
}')
curl http://ollama-server:11434/api/generate -d "$PAYLOAD"
  • Ollama — For running local AI code reviews via Gitea Actions.
  • Authentik — For centralized SSO and user management.
  • Ansible — For automating the deployment of Gitea itself.
  • Nextcloud — For syncing documentation and larger binary artifacts.
  • n8n — For orchestrating workflows triggered by Gitea webhooks.
  • Vikunja — For project management integrated with Gitea issues.
  • Paperless-ngx — For archiving documentation generated from Git repositories.
  • Model Context Protocol — Standard for integrating Gitea into AI agent workflows.
  • Forgejo — A community-driven fork of Gitea focusing on software freedom.
  • Argo CD — For Kubernetes-native GitOps using Gitea as a source.

Sources / references

Contribution Metadata

  • Last reviewed: 2026-07-21
  • Confidence: high