Gitea Has a Free API: Self-Host Your Own GitHub with Full REST and GraphQL APIs

#git #selfhosted #devops #tutorial

What is Gitea?

Gitea is a lightweight, self-hosted Git service — your own GitHub/GitLab in a single binary. It runs on a Raspberry Pi, a $5 VPS, or enterprise hardware.

Gitea includes repositories, issues, pull requests, CI/CD (Gitea Actions), packages, and a full REST API — all in a ~100MB binary.

Install

# Docker (recommended)
docker run -d --name gitea -p 3000:3000 -p 2222:22 \
  -v gitea-data:/data gitea/gitea:latest

# Or single binary
wget https://dl.gitea.com/gitea/latest/gitea-linux-amd64
chmod +x gitea-linux-amd64
./gitea-linux-amd64

The REST API

Gitea has a Swagger-documented REST API at https://your-gitea/api/swagger.

export GITEA_URL="https://git.myserver.com/api/v1"
export GITEA_TOKEN="your-token"

Repositories

# Create repo
curl -X POST "$GITEA_URL/user/repos" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "private": false, "auto_init": true}'

# List repos
curl -s "$GITEA_URL/user/repos" \
  -H "Authorization: token $GITEA_TOKEN" | jq '.[].full_name'

# Get repo info
curl -s "$GITEA_URL/repos/myuser/my-project" \
  -H "Authorization: token $GITEA_TOKEN" | jq '{name, stars: .stars_count, forks: .forks_count}'

Issues

# Create issue
curl -X POST "$GITEA_URL/repos/myuser/my-project/issues" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Bug: Login fails", "body": "Steps to reproduce...", "labels": [1, 2]}'

# List issues
curl -s "$GITEA_URL/repos/myuser/my-project/issues?state=open" \
  -H "Authorization: token $GITEA_TOKEN" | jq '.[].title'

# Add comment
curl -X POST "$GITEA_URL/repos/myuser/my-project/issues/1/comments" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Fixed in commit abc123"}'

Pull Requests

# Create PR
curl -X POST "$GITEA_URL/repos/myuser/my-project/pulls" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add user authentication",
    "head": "feature/auth",
    "base": "main",
    "body": "Implements JWT-based authentication"
  }'

# Merge PR
curl -X POST "$GITEA_URL/repos/myuser/my-project/pulls/1/merge" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"Do": "squash"}'

File Operations

# Create/update file
curl -X POST "$GITEA_URL/repos/myuser/my-project/contents/README.md" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "'$(echo -n "# My Project" | base64)'",
    "message": "Add README"
  }'

# Read file
curl -s "$GITEA_URL/repos/myuser/my-project/contents/README.md" \
  -H "Authorization: token $GITEA_TOKEN" | jq -r '.content' | base64 -d

Gitea Actions (CI/CD)

Gitea Actions are compatible with GitHub Actions:

# .gitea/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test