Gitea: The Lightweight Git Hosting Platform for Teams and Individuals

GitHub revolutionized how developers collaborate on code, but relying on a third-party service for your most valuable intellectual property comes with risks: service outages, policy changes, account suspensions, and the simple fact that your private code lives on someone else's servers. GitLab offers a self-hosted alternative, but it is a resource-hungry monolith that demands significant infrastructure. Enter Gitea—a fast, lightweight, single-binary Git hosting platform that delivers 90% of GitHub's functionality at 5% of the resource cost.

1. What Is Gitea?

Gitea is an open-source, self-hosted Git service that provides a web-based interface for managing Git repositories, code reviews, issue tracking, wikis, and CI/CD pipelines. It was forked from Gogs in 2016, born from a desire for a more community-driven development model and faster feature development. The name "Gitea" combines "Git" with "tea," reflecting its origins (Gogs was named after a Scottish slang for "goblet of tea").

The problem Gitea solves is clear: how do you get GitHub-like functionality on your own server without the massive overhead of GitLab? Whether you are a solo developer who wants a private code repository, a small team that needs pull requests and issue tracking, or an organization that requires on-premises code hosting for compliance reasons, Gitea provides a complete solution that runs on hardware as modest as a Raspberry Pi.

Gitea is written in Go and distributed as a single binary file. There are no runtime dependencies to install, no database server to configure (it supports SQLite out of the box), and no web server required (it has one built-in). This makes deployment trivially simple—you can go from zero to a running Git server in under five minutes.

2. Key Features

Repository Management

Gitea provides a full-featured repository management interface:

Git operations: push, pull, clone, fork—all standard Git functionality
Repository settings: public/private, wiki, issues, pull requests toggles per repo
Branch protection: require pull request reviews, status checks, and signed commits
Tags and releases: create releases with attached binaries
Web editor: edit files directly in the browser without cloning
Migration tools: import repositories from GitHub, GitLab, Gitea, Gogs, Bitbucket, OneDev, and Codeberg

Pull Requests and Code Review

Gitea's pull request system closely mirrors GitHub's:

Inline code comments: comment on specific lines of code
Review system: approve, request changes, or comment on PRs
Merge strategies: merge commit, squash, rebase, or rebase-merge
Conflict resolution: web-based conflict resolution for simple cases
Draft PRs: mark pull requests as work-in-progress
Auto-merge: automatically merge when all checks pass
Dependent PRs: reference related pull requests and issues

Issue Tracking

Gitea includes a built-in issue tracker with:

Labels: categorize issues with color-coded labels
Milestones: group issues into releases or sprints
Boards: Kanban-style project boards for visual task management
Time tracking: log time spent on issues
Issue templates: pre-fill issue descriptions with templates
Dependencies: link issues that block or are blocked by other issues
Cross-references: mention issues across repositories with owner/repo#123

Gitea Actions (CI/CD)

One of Gitea's most significant recent additions is Gitea Actions, a built-in CI/CD system that is compatible with GitHub Actions:

Workflow files: use the same YAML syntax as GitHub Actions
Reusable workflows: share workflows across repositories
Self-hosted runners: run jobs on your own infrastructure
Marketplace compatibility: many GitHub Actions can be used directly
Matrix builds: run jobs across multiple environments
Secrets and variables: store encrypted secrets for CI/CD pipelines
Artifact management: store and share build artifacts

This means you can migrate from GitHub to Gitea and often reuse your existing workflow files with minimal or no changes.

Wiki and Documentation

Every repository can have an integrated wiki, using Git itself as the storage backend. The wiki supports Markdown and offers a simple web-based editor. For more advanced documentation needs, Gitea sites can be configured with static site generators.

Organization and Team Management

Organizations: create groups with shared repositories
Teams: organize members into teams with different permission levels
Repository transfer: transfer ownership between users and organizations
Access tokens: generate API tokens for automation
OAuth2 provider: Gitea can act as an OAuth2 identity provider

Package Registry

Gitea includes a built-in package registry supporting:

npm (Node.js)
Cargo (Rust)
Composer (PHP)
Conan (C/C++)
Container (Docker/OCI)
Debian (apt)
Generic (any file type)
Helm (Kubernetes)
Maven (Java)
NuGet (.NET)
Pub (Dart)
RubyGems (Ruby)
Vagrant

This transforms Gitea from a code hosting platform into a complete DevOps toolkit.

API and Webhooks

Gitea provides a comprehensive REST API (Swagger-documented) and supports webhooks for integration with external services like Slack, Discord, Microsoft Teams, and custom endpoints. An experimental GraphQL API is also available.

Multi-Language Support

Gitea's interface is translated into over 30 languages, making it accessible to development teams worldwide.

3. Technical Architecture

Gitea is engineered for simplicity and performance:

Language: Written entirely in Go (Golang), which compiles to a single static binary with no runtime dependencies.
Web Framework: Uses Chi (a lightweight HTTP router) and Go's standard html/template for server-side rendering.
Database: Supports SQLite (default, zero-config), MySQL/MariaDB, and PostgreSQL. SQLite is sufficient for most small-to-medium deployments.
Frontend: Uses Vanilla JS with jQuery and Fomantic-UI for components. The approach is deliberately lightweight—no heavy SPA framework.
SSH: Built-in SSH server for Git operations over SSH, with configurable ports and key management.
Storage: File-based storage for repository data (standard Git bare repositories), with support for object storage backends (local, MinIO/S3) for LFS and attachments.

The design philosophy emphasizes:

1. Simplicity: single binary, minimal dependencies, easy to understand
2. Performance: Go's compiled nature and efficient concurrency model
3. Portability: runs on Linux, macOS, Windows, ARM, and even BSD
4. Community governance: decisions made openly, contributions welcomed

A typical Gitea instance uses 50-150MB of RAM and minimal CPU—compare this to GitLab, which typically requires 4GB+ RAM just to start.

4. Quick Deployment with Docker

Prerequisites

Docker and Docker Compose installed
A domain name (optional, for production use)

docker-compose.yml

version: "3.8" services: gitea: image: gitea/gitea:latest container_name: gitea environment: - USER_UID=1000 - USER_GID=1000 - GITEA__server__DOMAIN=gitea.yourdomain.com - GITEA__server__ROOT_URL=https://gitea.yourdomain.com/ - GITEA__server__HTTP_PORT=3000 - GITEA__server__SSH_PORT=22 - GITEA__database__DB_TYPE=postgres - GITEA__database__HOST=db:5432 - GITEA__database__NAME=gitea - GITEA__database__USER=gitea - GITEA__database__PASSWD=gitea_password volumes: - ./gitea_data:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "3000:3000" - "2222:22" depends_on: - db restart: unless-stopped

db: image: postgres:16-alpine container_name: gitea-db environment: - POSTGRES_USER=gitea - POSTGRES_PASSWORD=gitea_password - POSTGRES_DB=gitea volumes: - ./postgres_data:/var/lib/postgresql/data restart: unless-stopped

Step-by-Step Deployment

1. Create the project directory:

   mkdir -p ~/gitea/{gitea_data,postgres_data}

   cd ~/gitea

2. Create the docker-compose.yml (use the content above)

3. Start the containers:

   docker compose up -d

4. Complete the installation wizard:
Navigate to http://localhost:3000. The first-run installer will confirm your database settings and let you configure:
- Site title
- Server domain
- SSH port
- Admin account (optional; the first registered user becomes admin)

5. Set up a reverse proxy with SSL (recommended for production):

   gitea.yourdomain.com {

       reverse_proxy localhost:3000

   }

6. Configure SSH access (for Git operations over SSH):
The docker-compose maps container port 22 to host port 2222. Users can clone via:

   git clone ssh://[email protected]:2222/user/repo.git

7. Set up Gitea Actions runner (optional, for CI/CD):

   docker run -d --name gitea-runner \

     -v /var/run/docker.sock:/var/run/docker.sock \

     -v gitea_runner_data:/data \

     -e GITEA_INSTANCE_URL=https://gitea.yourdomain.com \

     -e GITEA_RUNNER_REGISTRATION_TOKEN=your_token \

     gitea/act_runner:latest

Simple SQLite Deployment (for testing)

For a quick test or small deployment, you can skip PostgreSQL and use SQLite:

version: "3.8"

services: gitea: image: gitea/gitea:latest container_name: gitea environment: - USER_UID=1000 - USER_GID=1000 volumes: - ./gitea_data:/data ports: - "3000:3000" - "2222:22" restart: unless-stopped

This requires only one container and is perfect for personal use or evaluation.

5. Comparison with Alternatives

| Feature | Gitea | GitLab CE | GitHub |
|---|---|---|---|
| License | MIT | GPL (CE) | Proprietary |
| Self-Hosting | Yes | Yes | No |
| Resource Usage | ~50-150MB RAM | ~4GB+ RAM | N/A (cloud) |
| Database | SQLite/MySQL/PostgreSQL | PostgreSQL | N/A |
| CI/CD | Gitea Actions (GitHub-compatible) | GitLab CI (built-in) | GitHub Actions |
| Issue Tracking | Built-in | Built-in (advanced) | Built-in |
| Wiki | Built-in | Built-in | Built-in (per-repo) |
| Container Registry | Built-in | Built-in | GitHub Container Registry |
| Package Registry | Multi-format | Multi-format | Limited (npm, containers) |
| Code Review | Pull requests | Merge requests | Pull requests |
| Pages | Gitea Pages (plugin) | GitLab Pages | GitHub Pages |
| Setup Complexity | Very low | High | N/A |
| Binary Size | ~100MB single binary | Multiple services | N/A |
| Deployment Time | Minutes | 30+ minutes | Instant (cloud) |

GitLab CE is the most feature-complete self-hosted option, offering advanced CI/CD, container scanning, dependency scanning, auto-devops, and a massive feature set. However, it is extremely resource-hungry, complex to maintain, and can be overwhelming for small teams. GitLab's "everything included" philosophy means you get features you may never use, at the cost of complexity.

GitHub remains the most popular code hosting platform with the largest community, best discoverability, and the most third-party integrations. However, it is a cloud-only service (GitHub Enterprise Server exists but is expensive), and relying on it means your code is on someone else's servers.

Gitea occupies the sweet spot for teams that want self-hosted Git hosting without the overhead. It covers all the essential features—repositories, pull requests, issues, CI/CD, wikis, package registries—while remaining lightweight enough to run on a $5 VPS or a Raspberry Pi.

6. FAQ

Can I migrate from GitHub to Gitea?

Yes. Gitea has a built-in migration tool that can import repositories, issues, pull requests, labels, milestones, and releases from GitHub, GitLab, Gogs, Bitbucket, and other platforms. Simply go to "New Migration" in the Gitea dashboard and provide the source repository URL and an access token. Gitea will fetch and import everything automatically.

Is Gitea suitable for large organizations?

Gitea works well for small to medium organizations (up to a few hundred users). For very large organizations with thousands of users and complex access control requirements, GitLab may be more appropriate due to its more granular permission system and enterprise features (LDAP/AD integration is available in both, but GitLab has more advanced group management). However, many organizations successfully run Gitea at scale, and the project continues to improve its enterprise capabilities.

How does Gitea Actions compare to GitHub Actions?

Gitea Actions is designed to be compatible with GitHub Actions. It uses the same YAML workflow syntax, supports the same job/step structure, and can run many GitHub Actions from the marketplace directly. The key difference is that Gitea Actions uses self-hosted runners (via act_runner) rather than GitHub's hosted runners. You provide the compute infrastructure, which gives you full control over the build environment but requires you to manage the runners yourself.

Can I use Gitea without Docker?

Absolutely. Since Gitea is a single Go binary, you can download it directly and run it:

wget https://dl.gitea.com/gitea/1.22/gitea-1.22-linux-amd64
chmod +x gitea-1.22-linux-amd64
./gitea-1.22-linux-amd64 web

This is one of Gitea's biggest advantages—no runtime dependencies, no JVM, no Node.js, just a single executable file.

7. Who Should Use This?

Gitea is ideal for:

Individual developers who want a private, self-hosted repository for personal projects
Small teams (2-50 developers) who need code review, issue tracking, and CI/CD without enterprise overhead
Homelab enthusiasts running services on limited hardware (Raspberry Pi, low-end VPS)
Organizations with compliance requirements that mandate on-premises code hosting
Open-source projects that want a self-hosted alternative to GitHub
Educational institutions that need a low-cost Git platform for teaching

Limitations to consider:

The UI, while functional, is less polished than GitHub or GitLab
Advanced CI/CD features (like GitLab's auto-devops or security scanning) are not built-in
The ecosystem of third-party integrations is smaller than GitHub's
Enterprise features like SSO, audit logs, and advanced RBAC are more limited than GitLab
Large-scale deployments (thousands of users) may require tuning and optimization

If you need the most features possible and have the hardware to support it, GitLab CE is the better choice. If you want a simple, fast, lightweight Git server that just works, Gitea is unbeatable.

Verdict

Gitea is the poster child for lightweight self-hosted software. It takes the core functionality that 90% of development teams actually need—Git hosting, pull requests, issues, CI/CD, and wikis—and packages it into a single binary that runs on almost anything. Its compatibility with GitHub Actions workflows makes migration seamless, and its resource efficiency means you can run it on hardware that GitLab would laugh at. For small teams, individual developers, and anyone who values simplicity and performance, Gitea is the best self-hosted Git platform available.

GitHub Repository: go-gitea/gitea

Gitea: The Lightweight Git Hosting Platform