# Woodpecker CI with Gitea

> Lightweight CI/CD platform integrated with Gitea for automated builds.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: woodpecker-server, woodpecker-agent, gitea, postgresql
- Tags: ci-cd, woodpecker, gitea, automation, builds
- Source: https://docker.recipes/devops/woodpecker-ci-gitea

## Overview

Woodpecker CI is a lightweight, cloud-native continuous integration and continuous deployment platform built on a simple yet powerful architecture. Originally forked from Drone CI, Woodpecker focuses on simplicity and container-first workflows, using YAML-based pipeline definitions that execute inside Docker containers. The platform follows a distributed architecture with a central server managing builds and lightweight agents executing the actual pipeline steps. This stack combines Woodpecker CI with Gitea, a minimal self-hosted Git service that provides GitHub-like functionality with significantly lower resource requirements. The integration creates a complete DevOps pipeline where Gitea handles source code management, issue tracking, and pull requests, while Woodpecker automatically triggers builds, tests, and deployments based on repository events. PostgreSQL serves as the backbone database for both services, storing repository metadata, build histories, user accounts, and pipeline configurations. This combination delivers enterprise-grade CI/CD capabilities without the overhead of larger platforms like GitLab or Jenkins, making it ideal for teams that need full control over their development infrastructure while maintaining operational simplicity.

## Features

- Automatic webhook integration between Gitea repositories and Woodpecker pipelines
- YAML-based pipeline definitions with multi-stage builds and parallel execution
- Docker-native build environment with isolated container execution per step
- Built-in secrets management with repository and organization-level scope
- Matrix builds supporting multiple versions, environments, and configurations
- Pull request validation with status checks integrated into Gitea's review process
- Pipeline visualization with real-time logs and build artifact management
- Multi-agent architecture supporting distributed builds across different machines

## Use cases

- Small to medium development teams requiring private Git hosting with integrated CI/CD
- Organizations migrating from hosted services to self-managed infrastructure for compliance
- Homelab and personal projects needing automated testing and deployment pipelines
- Educational environments teaching DevOps practices without cloud service dependencies
- Startups and agencies managing multiple client projects with isolated CI/CD workflows
- Companies requiring air-gapped development environments with full source control
- Development teams building containerized applications with Docker-based testing

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM
- Ports 3000, 8000, and 222 available for Gitea web, Woodpecker web, and Gitea SSH respectively
- Domain names or accessible hostnames for proper OAuth application configuration
- Docker socket access for Woodpecker agent to spawn build containers
- Basic understanding of Git workflows and YAML syntax for pipeline creation
- SSL certificates if deploying with HTTPS in production environments

## docker-compose.yml

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
    volumes:
      - gitea-data:/data
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db
    networks:
      - woodpecker-network
    restart: unless-stopped

  woodpecker-server:
    image: woodpeckerci/woodpecker-server:latest
    container_name: woodpecker-server
    environment:
      - WOODPECKER_OPEN=true
      - WOODPECKER_HOST=${WOODPECKER_HOST}
      - WOODPECKER_GITEA=true
      - WOODPECKER_GITEA_URL=${GITEA_URL}
      - WOODPECKER_GITEA_CLIENT=${GITEA_CLIENT_ID}
      - WOODPECKER_GITEA_SECRET=${GITEA_CLIENT_SECRET}
      - WOODPECKER_AGENT_SECRET=${AGENT_SECRET}
      - WOODPECKER_DATABASE_DRIVER=postgres
      - WOODPECKER_DATABASE_DATASOURCE=postgres://woodpecker:${WP_DB_PASSWORD}@db:5432/woodpecker?sslmode=disable
    volumes:
      - woodpecker-data:/var/lib/woodpecker
    ports:
      - "8000:8000"
    depends_on:
      - db
      - gitea
    networks:
      - woodpecker-network
    restart: unless-stopped

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:latest
    container_name: woodpecker-agent
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=${AGENT_SECRET}
      - WOODPECKER_MAX_WORKFLOWS=4
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - woodpecker-server
    networks:
      - woodpecker-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: woodpecker-db
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=gitea
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./init-db.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - woodpecker-network
    restart: unless-stopped

volumes:
  gitea-data:
  woodpecker-data:
  postgres-data:

networks:
  woodpecker-network:
    driver: bridge
```

## .env

```bash
# Woodpecker CI with Gitea
DB_PASSWORD=secure_db_password
WP_DB_PASSWORD=secure_wp_password

# Gitea
GITEA_URL=http://localhost:3000

# Woodpecker
WOODPECKER_HOST=http://localhost:8000
GITEA_CLIENT_ID=your_oauth_client_id
GITEA_CLIENT_SECRET=your_oauth_client_secret
AGENT_SECRET=super_secret_agent_key
```

## Usage notes

- Gitea at http://localhost:3000
- Woodpecker at http://localhost:8000
- Create OAuth app in Gitea settings
- Add .woodpecker.yml to repos
- Supports Docker-based pipelines

## Troubleshooting

- OAuth application not found error: Verify GITEA_CLIENT_ID and GITEA_CLIENT_SECRET match the OAuth app created in Gitea admin settings
- Woodpecker agent not connecting: Check AGENT_SECRET matches between server and agent, and ensure agent can reach server on port 9000
- Pipeline failing to clone repository: Confirm Gitea is accessible from Woodpecker containers and SSH keys or tokens are properly configured
- Database connection refused: Ensure PostgreSQL container is fully started before Gitea and Woodpecker attempt connections, add healthchecks if needed
- Permission denied on Docker socket: Verify woodpecker-agent container has proper access to /var/run/docker.sock or consider using rootless Docker
- Build artifacts not persisting: Check volume mounts and ensure workspace directories are properly configured in pipeline steps

