# Gitea — Lightweight Self-Hosted Git Service

> Gitea is a painless self-hosted Git service with code hosting, review, CI/CD, package registry, and project management — a lightweight GitHub/GitLab alternative.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name gitea -p 3000:3000 -p 2222:22 -v gitea-data:/data gitea/gitea:latest
```

Open `http://localhost:3000` — complete the installation wizard and create your first repository.

## Intro

**Gitea** is a lightweight, self-hosted Git service that provides a complete software development platform. Written in Go, it's designed to be simple to install and run, offering GitHub-like features including code hosting, pull requests, code review, CI/CD (Gitea Actions), package registry, and project management — all in a single binary.

With 54.8K+ GitHub stars and MIT license, Gitea is one of the most popular self-hosted Git solutions, valued for its low resource usage, ease of deployment, and comprehensive feature set.

## What Gitea Does

Gitea provides a full software development lifecycle:

- **Git Hosting**: Repository management with branch protection, webhooks, and deploy keys
- **Code Review**: Pull requests with inline comments, reviews, approvals, and merge strategies
- **Issue Tracking**: Issues with labels, milestones, projects, and kanban boards
- **CI/CD**: Gitea Actions (GitHub Actions compatible) for automated workflows
- **Package Registry**: Host Docker images, npm, Maven, PyPI, NuGet, and more
- **Wiki**: Built-in wiki for project documentation
- **Organizations & Teams**: Multi-user with organization structure and team permissions

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Web UI      │────▶│  Gitea       │────▶│  SQLite /    │
│  (Go + Vue)  │     │  Server (Go) │     │  PostgreSQL /│
└──────────────┘     └──────┬───────┘     │  MySQL       │
                            │             └──────────────┘
                     ┌──────┴───────┐
                     │  Git Repos   │
                     │  (Filesystem)│
                     └──────────────┘
```

Gitea runs as a single binary with embedded web server and Git operations. It supports SQLite (zero-config), PostgreSQL, MySQL, and MSSQL as database backends.

## Installation Options

### Docker (Recommended)

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    ports:
      - "3000:3000"    # Web UI
      - "2222:22"      # SSH
    environment:
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: gitea
      GITEA__database__USER: gitea
      GITEA__database__PASSWD: gitea
    volumes:
      - gitea-data:/data
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: gitea
      POSTGRES_DB: gitea
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  gitea-data:
  pg-data:
```

### Single Binary

```bash
# Download and run directly
wget https://dl.gitea.com/gitea/latest/gitea-latest-linux-amd64
chmod +x gitea-latest-linux-amd64
./gitea-latest-linux-amd64 web
```

### Kubernetes with Helm

```bash
helm repo add gitea https://dl.gitea.com/charts/
helm install gitea gitea/gitea --namespace gitea --create-namespace
```

## Key Features

### Gitea Actions (CI/CD)

Gitea Actions is compatible with GitHub Actions syntax:

```yaml
# .gitea/workflows/ci.yaml
name: CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test
      - run: npm run build
```

### Package Registry

Host your own packages alongside code:

```bash
# Docker registry
docker tag myapp:latest gitea.example.com/org/myapp:latest
docker push gitea.example.com/org/myapp:latest

# npm registry
npm publish --registry=https://gitea.example.com/api/packages/org/npm/
```

Supported package types: Docker, npm, PyPI, Maven, NuGet, Cargo, Composer, Conan, Conda, Go, Helm, and more.

### Migration Tools

Easily migrate from other platforms:

```
Supported sources:
├── GitHub (repos, issues, PRs, wiki, labels, milestones)
├── GitLab (repos, issues, PRs, labels)
├── Bitbucket
├── Gogs
└── Gitea (other instances)
```

## Resource Comparison

| Metric | Gitea | GitLab CE | Gogs |
|--------|-------|-----------|------|
| RAM (idle) | ~150MB | ~2GB | ~100MB |
| Binary size | ~100MB | 2GB+ (install) | ~60MB |
| CI/CD | Built-in (Actions) | Built-in | External |
| Package registry | Yes | Yes | No |
| Container registry | Yes | Yes | No |

## Gitea vs Alternatives

| Feature | Gitea | GitHub | GitLab CE | Gogs |
|---------|-------|--------|-----------|------|
| Open Source | Yes (MIT) | No | Yes (MIT) | Yes (MIT) |
| Self-hosted | Yes | Enterprise | Yes | Yes |
| CI/CD | Gitea Actions | GitHub Actions | GitLab CI | External |
| Package registry | Yes | Yes | Yes | No |
| Resource usage | Low | N/A | High | Very low |
| Actions compat. | GitHub Actions | Native | Own syntax | No |

## FAQ

**Q: Gitea or GitLab?**
A: If you need a lightweight, low-resource Git service, pick Gitea (150MB RAM vs GitLab's 2GB+). If you need an enterprise DevOps platform (built-in CI/CD, security scanning, container registry), pick GitLab.

**Q: How compatible is Gitea Actions with GitHub Actions?**
A: Most GitHub Actions workflows run on Gitea directly. Common actions like actions/checkout and actions/setup-node are supported. A few actions that depend on GitHub-specific APIs may need adjustment.

**Q: Can I migrate from GitHub/GitLab?**
A: Yes. Gitea has a built-in migration tool that supports one-click migration of repositories, issues, PRs, and wikis from GitHub, GitLab, Bitbucket, and more.

## Source & Thanks

- GitHub: [go-gitea/gitea](https://github.com/go-gitea/gitea) — 54.8K+ ⭐ | MIT
- Website: [gitea.com](https://gitea.com)

---
Source: https://tokrepo.com/en/workflows/gitea-lightweight-self-hosted-git-service-60bf33b1
Author: Script Depot