Gitea: Self-Hosted Git Server Setup, Migration, and Troubleshooting

Why Gitea?

GitHub and GitLab are great, but sometimes you need to own your code hosting:

Privacy — Code stays on your servers, not a third-party cloud.
Lightweight — Runs on 200 MB RAM (GitLab needs 4+ GB).
GitHub Actions compatible — Reuse existing CI/CD workflows.
Free & open source — MIT licensed, no per-seat fees.

Prerequisites

Linux server with Docker (or Go 1.21+ for binary install).
At least 512 MB RAM (1 GB recommended).
A domain name for HTTPS access (optional but recommended).

Step 1: Deploy with Docker Compose

# docker-compose.yml
version: "3"
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=sqlite3
    volumes:
      - ./gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    restart: always

docker compose up -d

Access at http://your-server:3000. Complete the initial setup wizard.

Step 2: Migrate from GitHub/GitLab

Click the + icon → New Migration.
Select GitHub (or GitLab, Bitbucket, etc.).
Enter the repository URL and a personal access token with repo scope.
Check what to import: Issues, Labels, Milestones, Releases, Pull Requests.
Click Migrate Repository.

Gitea preserves commit history, branches, tags, and issue numbers.

Step 3: Enable Gitea Actions (CI/CD)

Enable in Configuration

Add to gitea-data/gitea/conf/app.ini:

[actions]
ENABLED = true

Restart Gitea: docker compose restart

Install and Register a Runner

# Download act_runner
wget https://gitea.com/gitea/act_runner/releases/latest/download/act_runner-linux-amd64
chmod +x act_runner-linux-amd64

# Register with your Gitea instance
./act_runner-linux-amd64 register \
  --instance http://your-gitea:3000 \
  --token YOUR_RUNNER_TOKEN

# Start the runner
./act_runner-linux-amd64 daemon

Example Workflow (`.gitea/workflows/ci.yml`)

name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Gitea Actions!"
      - run: npm test

Troubleshooting

Problem	Solution
Can’t push via SSH	Check SSH key in Settings, verify port 2222 is mapped, test with `ssh -T git@server -p 2222`
”Repository not found” on clone	Verify the repo URL includes the correct user/org and repo name
Migration fails with 401	The access token is missing or expired; generate a new one with `repo` scope
Actions workflow not triggering	Ensure `ENABLED = true` in app.ini, runner is online, and `.gitea/workflows/` directory is used
Database locked (SQLite)	Switch to PostgreSQL for multi-user setups; SQLite doesn’t handle concurrent writes well

Summary

Gitea is a lightweight GitHub alternative running on minimal resources.
Migrate repos with the built-in migration tool preserving issues and PRs.
Gitea Actions is GitHub Actions compatible — reuse existing workflows.
Use PostgreSQL instead of SQLite for teams with 5+ concurrent users.

Frequently Asked Questions

What is Gitea and how does it compare to GitHub or GitLab?

Gitea is a lightweight, self-hosted Git service written in Go. It uses only 200 MB of RAM compared to GitLab's 4+ GB. It provides repositories, issues, pull requests, wikis, and CI/CD (Gitea Actions). It's ideal for small teams, homelabs, or organizations that need data sovereignty without the resource overhead of GitLab.

Can I migrate my repositories from GitHub to Gitea?

Yes. Gitea has a built-in migration tool that imports repositories, issues, labels, milestones, releases, and pull requests from GitHub, GitLab, Bitbucket, and other Gitea instances. Go to New Migration in the web UI and enter the source URL with an access token.

Does Gitea support CI/CD pipelines?

Yes, Gitea Actions (available since Gitea 1.19) is compatible with GitHub Actions workflow syntax. You can reuse most GitHub Actions YAML files directly. You need to run a Gitea Runner (act_runner) on a separate machine or as a Docker container.

Why can't I push via SSH to Gitea?

Common causes: the SSH server isn't running on port 22 (Gitea uses its built-in SSH by default on port 2222), your SSH key isn't added in Settings > SSH Keys, or the authorized_keys file has wrong permissions. Check with ssh -T git@your-gitea-server -p 2222.