# Gitea with Actions Runner

> Self-hosted Git with Gitea and integrated CI/CD runners.

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

## Overview

Gitea is a lightweight, self-hosted Git service written in Go that provides GitHub-like functionality without the resource overhead of larger alternatives like GitLab. Originally forked from Gogs in 2016, Gitea has evolved into a mature platform offering repository management, issue tracking, pull requests, and built-in CI/CD through Gitea Actions. This makes it an ideal choice for teams wanting complete control over their source code and development workflow while maintaining familiar GitHub-style interfaces and workflows.

This stack combines Gitea with PostgreSQL for robust data persistence, Redis for high-performance caching and session management, and the official Gitea Actions runner for automated CI/CD pipelines. PostgreSQL ensures ACID compliance and handles complex queries efficiently, while Redis dramatically improves Gitea's response times by caching frequently accessed data. The Actions runner provides Docker-in-Docker capabilities, enabling teams to run sophisticated build, test, and deployment pipelines using GitHub Actions-compatible workflow syntax.

This configuration targets development teams, DevOps engineers, and organizations requiring private Git hosting with integrated CI/CD capabilities. Small to medium-sized companies benefit from reduced licensing costs compared to hosted solutions, while maintaining enterprise-grade features like OAuth2 authentication, webhook integrations, and scalable runner architecture. The stack is particularly valuable for teams with compliance requirements, air-gapped environments, or those wanting to avoid vendor lock-in while preserving familiar Git workflows.

## Features

- GitHub Actions-compatible CI/CD workflows with YAML syntax support
- PostgreSQL backend providing ACID transactions and advanced querying capabilities
- Redis caching layer for sub-millisecond session and repository data access
- Docker-in-Docker runner execution supporting multi-stage builds and custom images
- Built-in package registry supporting Docker, npm, Maven, and NuGet packages
- OAuth2 and LDAP authentication with role-based access control
- Pull request workflows with code review, approvals, and merge protection
- Issue tracking with milestones, labels, and project boards

## Use cases

- Private source code hosting for proprietary software development
- Self-hosted CI/CD pipelines replacing Jenkins or GitHub Actions
- Code review workflows for distributed development teams
- Package registry for internal libraries and Docker images
- Migration from GitHub or GitLab to reduce licensing costs
- Compliance-driven development in regulated industries
- Air-gapped development environments in secure facilities

## Prerequisites

- Minimum 1GB RAM (2GB+ recommended for active CI/CD workloads)
- Docker host with /var/run/docker.sock access for runner container
- Ports 3000 and 2222 available for HTTP and SSH Git access
- Basic understanding of Git workflows and YAML syntax
- PostgreSQL administration knowledge for backup and maintenance
- Environment variables POSTGRES_PASSWORD and RUNNER_TOKEN configured

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=gitea
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - gitea_net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - gitea_net

  gitea:
    image: gitea/gitea:latest
    ports:
      - "3000:3000"
      - "2222:22"
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=postgres:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${POSTGRES_PASSWORD}
      - GITEA__cache__ADAPTER=redis
      - GITEA__cache__HOST=redis://redis:6379/0
      - GITEA__actions__ENABLED=true
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      - postgres
      - redis
    networks:
      - gitea_net

  gitea-runner:
    image: gitea/act_runner:latest
    environment:
      - GITEA_INSTANCE_URL=http://gitea:3000
      - GITEA_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
      - GITEA_RUNNER_NAME=docker-runner
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - runner_data:/data
    depends_on:
      - gitea
    networks:
      - gitea_net

volumes:
  postgres_data:
  redis_data:
  gitea_data:
  runner_data:

networks:
  gitea_net:
```

## .env

```bash
# Gitea with Actions
POSTGRES_PASSWORD=secure_postgres_password
RUNNER_TOKEN=your_runner_registration_token

# Gitea at http://localhost:3000
# SSH at localhost:2222
# Get runner token from Gitea admin panel
```

## Usage notes

- Gitea at http://localhost:3000
- SSH clone via port 2222
- Enable Actions in admin settings
- Get runner token from Site Admin > Actions > Runners
- GitHub Actions compatible workflow files

## Troubleshooting

- Runner registration fails with 'token invalid': Generate new runner token from Site Admin > Actions > Runners and update RUNNER_TOKEN environment variable
- Actions workflows stuck in 'waiting' status: Verify runner container has access to Docker socket and check runner logs for connection issues
- Gitea shows 'database connection failed': Ensure PostgreSQL container is healthy and POSTGRES_PASSWORD matches between services
- SSH clone fails on port 2222: Check if host firewall allows port 2222 and verify SSH_PORT setting in Gitea configuration
- Redis connection errors in Gitea logs: Confirm Redis container is running and accessible on gitea_net network
- Actions runner out of disk space: Configure Docker cleanup policies and monitor /var/lib/docker usage on host system

