# Forgejo with Actions Runner

> Forgejo Git forge with GitHub Actions compatible CI/CD runners.

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

## Overview

Forgejo is a self-hosted Git forge that emerged as a community-driven fork of Gitea, focusing on federation capabilities and user freedom. It provides comprehensive Git repository hosting with built-in issue tracking, pull requests, wikis, and project management features. What sets Forgejo apart is its commitment to remaining fully community-owned and its development of ActivityPub federation for decentralized collaboration across instances. This stack combines Forgejo with its dedicated Actions Runner to create a complete GitHub-alternative CI/CD platform. The PostgreSQL database handles repository metadata, user accounts, and issue tracking, while Redis accelerates session management and caches frequently accessed data. The Docker-in-Docker (DinD) container provides isolated build environments for CI/CD pipelines, ensuring that Actions workflows run securely without affecting the host system. This configuration is ideal for organizations seeking GitHub functionality with complete control over their code and infrastructure. Teams migrating from GitHub will find familiar Actions syntax compatibility, while the federation features position this stack for future decentralized development workflows. The combination delivers enterprise-grade Git hosting with modern CI/CD capabilities, all under open-source licenses.

## Features

- GitHub Actions compatible workflow syntax with .forgejo/workflows/ directory support
- ActivityPub federation protocol for cross-instance collaboration and decentralized development
- Docker-in-Docker isolation for secure CI/CD pipeline execution without host contamination
- PostgreSQL JSONB storage for efficient Git metadata and issue tracking with complex queries
- Redis-backed session clustering and cache acceleration for multi-user repository access
- Forgejo Runner daemon with automatic job polling and distributed build execution
- Built-in container registry for Docker image publishing from CI/CD pipelines
- Advanced Git LFS support with PostgreSQL metadata tracking and Redis caching

## Use cases

- Self-hosted GitHub alternative for teams requiring code sovereignty and data control
- CI/CD automation for Docker applications with integrated container registry publishing
- Private Git hosting for sensitive projects with Actions-based testing and deployment
- Educational institutions teaching DevOps with GitHub-compatible workflow syntax
- Open source projects seeking federated collaboration across multiple Forgejo instances
- Compliance-focused organizations needing auditable Git operations and build processes
- Development teams migrating from GitHub while maintaining existing Actions workflows

## Prerequisites

- Minimum 2GB RAM for PostgreSQL database operations and Redis caching
- Docker host with privileged container support for Docker-in-Docker functionality
- Ports 3000 (web UI) and 222 (SSH Git access) available on the host system
- Basic understanding of Git forge administration and CI/CD workflow concepts
- SSL certificate setup knowledge for production HTTPS deployment
- Familiarity with GitHub Actions syntax for workflow creation and debugging

## docker-compose.yml

```yaml
services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:7
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=${DB_PASSWORD}
      - FORGEJO__cache__ADAPTER=redis
      - FORGEJO__cache__HOST=redis://redis:6379/0
      - FORGEJO__session__PROVIDER=redis
      - FORGEJO__session__PROVIDER_CONFIG=redis://redis:6379/1
      - FORGEJO__actions__ENABLED=true
    volumes:
      - forgejo-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db
      - redis
    networks:
      - forgejo-network
    restart: unless-stopped

  runner:
    image: code.forgejo.org/forgejo/runner:3.3.0
    container_name: forgejo-runner
    environment:
      - DOCKER_HOST=tcp://docker-in-docker:2376
      - DOCKER_TLS_VERIFY=1
      - DOCKER_CERT_PATH=/certs/client
    volumes:
      - runner-data:/data
      - docker-certs:/certs/client:ro
    depends_on:
      - forgejo
      - docker-in-docker
    networks:
      - forgejo-network
    restart: unless-stopped
    command: >
      sh -c "
        while ! nc -z forgejo 3000; do sleep 1; done;
        forgejo-runner daemon
      "

  docker-in-docker:
    image: docker:dind
    container_name: forgejo-dind
    privileged: true
    environment:
      - DOCKER_TLS_CERTDIR=/certs
    volumes:
      - docker-certs:/certs
      - dind-data:/var/lib/docker
    networks:
      - forgejo-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: forgejo-db
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=forgejo
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - forgejo-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: forgejo-redis
    volumes:
      - redis-data:/data
    networks:
      - forgejo-network
    restart: unless-stopped

volumes:
  forgejo-data:
  runner-data:
  docker-certs:
  dind-data:
  postgres-data:
  redis-data:

networks:
  forgejo-network:
    driver: bridge
```

## .env

```bash
# Forgejo with Actions
DB_PASSWORD=secure_forgejo_password

# Runner registration token (get from Forgejo admin)
RUNNER_TOKEN=your_runner_token
```

## Usage notes

- Forgejo at http://localhost:3000
- Register runner in Forgejo admin settings
- GitHub Actions compatible workflows
- Uses Docker-in-Docker for isolation
- Support for .forgejo/workflows/

## Troubleshooting

- Runner registration fails with 'connection refused': Ensure Forgejo is fully started before runner attempts registration, check network connectivity between containers
- Actions workflows fail with Docker permission errors: Verify docker-in-docker container is running with privileged mode and proper TLS certificate mounting
- PostgreSQL connection timeout during startup: Increase DB_PASSWORD complexity, check PostgreSQL container logs for authentication failures or resource constraints
- Redis session data not persisting: Confirm Redis volume mounting and check for Redis memory limits causing data eviction in high-traffic scenarios
- Forgejo web interface returns 500 errors: Check database migration status and ensure PostgreSQL has sufficient disk space for repository metadata
- Git clone operations timeout: Verify SSH port 222 accessibility and check Forgejo SSH key configuration for the git user

