# Gitea with Actions Runner

> Self-hosted Git with Gitea, built-in Actions CI/CD runner, and PostgreSQL backend.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: gitea, gitea-runner, postgresql, nginx
- Tags: gitea, git, ci-cd, actions, self-hosted
- Source: https://docker.recipes/devops/gitea-ci-stack

## Overview

Gitea is a lightweight, self-hosted Git service written in Go that provides GitHub-like functionality with minimal resource requirements. Born as a fork of Gogs in 2016, Gitea has evolved into a comprehensive Git platform offering repository hosting, pull requests, issue tracking, and built-in CI/CD capabilities through Gitea Actions. Its design philosophy emphasizes simplicity, performance, and ease of deployment, making it an excellent alternative to heavier solutions like GitLab for teams that need essential Git hosting features without the complexity.

This deployment creates a complete self-hosted Git platform with CI/CD capabilities using four interconnected services: the main Gitea application server, a PostgreSQL database for robust data storage, a dedicated Actions runner for executing CI/CD pipelines, and an Nginx reverse proxy for web traffic management. The PostgreSQL backend provides enterprise-grade reliability and performance compared to SQLite, while the integrated runner enables automated testing, building, and deployment workflows directly within your repositories. The Nginx frontend handles SSL termination, load balancing, and can serve static assets efficiently.

This stack is ideal for development teams, organizations, and individuals who need complete control over their Git infrastructure while maintaining the familiar GitHub-style workflow. The combination of Gitea's lightweight design with PostgreSQL's reliability makes it suitable for everything from personal projects to small-to-medium enterprise deployments, especially where data sovereignty, customization, and cost control are priorities.

## Features

- GitHub-compatible Actions CI/CD with dedicated runner container supporting Docker-based workflows
- PostgreSQL backend providing ACID compliance and advanced query capabilities for repository metadata
- Built-in pull request system with code review, diff viewing, and merge conflict resolution
- Issue tracking with milestones, labels, assignees, and project boards for agile development
- OAuth2 and LDAP authentication support for enterprise identity integration
- Repository mirroring and migration tools for GitHub, GitLab, and other Git platforms
- Webhook system for integrating with external services and custom automation
- Nginx reverse proxy with SSL/TLS termination and static file caching optimization

## Use cases

- Private Git hosting for proprietary codebases requiring data sovereignty and security control
- CI/CD automation for small to medium development teams with Docker-based build pipelines
- Code review workflows for distributed teams needing GitHub-like collaboration features
- Migration target for teams moving away from cloud Git providers to reduce costs
- Educational environments teaching Git workflows and DevOps practices with full infrastructure control
- Open source project hosting with integrated issue tracking and community contribution management
- Enterprise development environments requiring LDAP integration and custom authentication policies

## Prerequisites

- Docker and Docker Compose with at least 2GB RAM available for the complete stack
- Ports 80, 443, 3000, and 222 available on the host system for web and SSH access
- Valid SSL certificates placed in ./certs/ directory for HTTPS functionality
- Runner registration token generated from Gitea admin panel after initial setup
- Basic understanding of Git workflows, Docker containers, and CI/CD pipeline concepts
- Nginx configuration file (./nginx.conf) customized for your domain and SSL setup

## docker-compose.yml

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: ${POSTGRES_DB}
      GITEA__database__USER: ${POSTGRES_USER}
      GITEA__database__PASSWD: ${POSTGRES_PASSWORD}
      GITEA__actions__ENABLED: "true"
    ports:
      - "3000:3000"
      - "222:22"
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      db:
        condition: service_healthy
    networks:
      - gitea-net
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gitea-net
    restart: unless-stopped

  runner:
    image: gitea/act_runner:latest
    environment:
      CONFIG_FILE: /config.yaml
      GITEA_INSTANCE_URL: http://gitea:3000
      GITEA_RUNNER_REGISTRATION_TOKEN: ${RUNNER_TOKEN}
      GITEA_RUNNER_NAME: default-runner
    volumes:
      - runner_data:/data
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config.yaml:/config.yaml:ro
    depends_on:
      - gitea
    networks:
      - gitea-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - gitea
    networks:
      - gitea-net
    restart: unless-stopped

volumes:
  gitea_data:
  postgres_data:
  runner_data:

networks:
  gitea-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=gitea
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=gitea

# Runner Registration Token
# Get from Gitea Admin > Actions > Runners
RUNNER_TOKEN=your_runner_token_here
```

## Usage notes

- Gitea at http://localhost:3000
- SSH clone via port 222
- Enable Actions in repo settings
- Create runner token in admin panel

## Troubleshooting

- Runner container failing to register: Verify GITEA_RUNNER_REGISTRATION_TOKEN matches the token from Gitea admin settings and that the gitea service is fully started
- Database connection errors on startup: Ensure PostgreSQL environment variables match between gitea and db services, and wait for the health check to pass before Gitea starts
- SSH clone operations failing on port 222: Check that the port is not blocked by firewall and that SSH_PORT is correctly configured in Gitea settings
- Actions workflows stuck in pending: Verify /var/run/docker.sock is properly mounted in runner container and Docker daemon is accessible
- Nginx returning 502 Bad Gateway: Confirm gitea service is running and accessible on port 3000, and check nginx.conf upstream configuration
- PostgreSQL data corruption after restart: Ensure postgres_data volume has proper permissions and sufficient disk space for database operations

