How to Deploy and Use Gitea: A Lightweight Self‑Hosted Git Platform

Overview

Gitea is a lightweight, open‑source DevOps platform written in Go. It provides Git hosting, code review, issue tracking, CI/CD (Gitea Actions), package registry and basic project‑management features. The entire service runs as a single compiled binary, making installation and upgrades straightforward on Linux, macOS and Windows.

Goals

The project aims to deliver an extremely easy‑to‑install, fast, and self‑hosted Git service that works on x86, amd64, ARM and PowerPC architectures.

Key Technical Features

Full Git repository management – create, clone, branch, tag, cherry‑pick, and hook support.

Lightweight design: low CPU and memory footprint, suitable for small‑scale or resource‑constrained servers.

Simple deployment – no external runtime dependencies; the binary embeds SQLite, MySQL and PostgreSQL drivers.

Built‑in permission system with ACLs for fine‑grained access control.

Pull‑request based code review supporting both GitHub‑style and AGit workflows.

Gitea Actions – CI/CD engine compatible with GitHub Actions YAML syntax.

Project management via kanban boards, issues, milestones, labels, assignees and time tracking.

Package registry supporting more than 20 formats (e.g., Cargo, Helm, Maven, npm, PyPI, RubyGems, etc.).

Multi‑language UI and MIT‑licensed community development.

Comparison with Other Platforms

Scope: Gitea focuses on core Git hosting and essential collaboration tools; GitLab adds a full‑stack CI/CD, security scanning and wiki; GitHub provides the largest ecosystem and social features.

Deployment: Gitea is a single binary that can be placed on any server; GitLab requires a container or omnibus package with many services; GitHub is a hosted SaaS (Enterprise edition can be self‑hosted).

Extensibility: Gitea supports plugins and custom configuration but is not designed for massive horizontal scaling; GitLab offers extensive integration points; GitHub relies heavily on third‑party apps.

Installation (Binary on 64‑bit Linux)

Download the latest binary, make it executable, and place it in a directory that is in PATH (e.g., /usr/local/bin).

wget -O gitea https://dl.gitea.com/gitea/1.21.1/gitea-1.21.1-linux-amd64
chmod +x gitea
cp gitea /usr/local/bin/gitea

Create the required data directories and set appropriate ownership (the example uses a git user and group named www – adjust to your environment).

sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R www:www /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

Create the configuration directory:

sudo mkdir /etc/gitea
sudo chown root:www /etc/gitea
sudo chmod 770 /etc/gitea

Optionally export the working directory for Systemd or other init systems: export GITEA_WORK_DIR=/var/lib/gitea/ Start Gitea manually to verify the configuration file ( /etc/gitea/app.ini must exist; a minimal file can be generated with gitea generate).

GITEA_WORK_DIR=/var/lib/gitea/ /usr/local/bin/gitea web -c /etc/gitea/app.ini

Running as a Systemd Service

Create /etc/systemd/system/gitea.service with the following content (replace git user/group if needed):

[Unit]
Description=Gitea (Git with a cup of tea)
After=network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target

Enable the service to start at boot and launch it immediately:

sudo systemctl enable gitea
sudo systemctl start gitea
sudo systemctl status gitea.service

Tip: If you need to bind to a privileged port (<1024), add CapabilityBoundingSet=CAP_NET_BIND_SERVICE and AmbientCapabilities=CAP_NET_BIND_SERVICE to the [Service] section, or use a reverse proxy.

Nginx Reverse Proxy (Optional)

Expose Gitea on standard HTTP/HTTPS ports by proxying to the internal localhost:3000 listener:

server {
    listen 80;
    server_name git.example.com;
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

After updating DNS or /etc/hosts, the UI is reachable at http://git.example.com (or the server’s IP address).

Basic Usage

Once the web UI is accessible, create a repository, then push code from any Git client:

git push
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 214 bytes | 53.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: . Processing 1 references
remote: Processed 1 references in total
To http://git.example.com:3000/username/repo.git
 * [new branch]      main -> main