website-and-documentation/content/en/docs/edp/deployment/infrastructure/stacks/forgejo.md

title	linkTitle	weight	description
Forgejo	Forgejo	30	Self-hosted Git service with built-in CI/CD capabilities

Overview

Forgejo is a self-hosted Git service that provides repository hosting, code collaboration, and integrated CI/CD workflows. As part of the Edge Developer Platform, Forgejo serves as the central code repository and continuous integration system, offering a complete DevOps platform with Git hosting, issue tracking, and automated build pipelines.

The Forgejo stack deploys a Forgejo server instance with PostgreSQL database backend, MinIO object storage, and Forgejo Runners for executing CI/CD workflows.

Key Features

• Git Repository Hosting: Full-featured Git server with web interface for code management
• Built-in CI/CD: Forgejo Actions provide GitHub Actions-compatible workflow automation
• Issue Tracking: Integrated project management with issues, milestones, and pull requests
• Container Registry: Built-in Docker registry for container image storage
• Code Review: Pull request workflows with inline comments and approval processes
• Scalable Runners: Distributed runner architecture with Docker-in-Docker execution
• S3 Object Storage: MinIO integration for artifacts, LFS objects, and backups

Repository

Code: Forgejo Stack Templates

Documentation:

• Forgejo Official Documentation
• Forgejo Actions Documentation
• Forgejo Helm Chart Repository

Getting Started

Prerequisites

• Kubernetes cluster with ArgoCD installed (provided by core stack)
• CloudNativePG operator (provided by core stack)
• Ingress controller configured (provided by otc stack)
• cert-manager for TLS certificate management (provided by otc stack)
• Infrastructure deployed through Infra Deploy

Quick Start

The Forgejo stack is deployed as part of the EDP installation process:

1. Trigger Deploy Pipeline

   • Go to Infra Deploy Pipeline
   • Click on Run workflow
   • Enter a name in "Select environment directory to deploy". This must be DNS Compatible. (if you enter test-me then the domain will be forgejo.test-me.t09.de)
   • Execute workflow

2. ArgoCD Synchronization ArgoCD automatically deploys:

   • Forgejo server (Helm chart v12.0.0)
   • PostgreSQL database cluster (CloudNativePG)
   • Forgejo Runners with Docker-in-Docker execution
   • Ingress configuration with TLS
   • Database credentials and storage secrets

Verification

Verify the Forgejo deployment:

# Check ArgoCD applications status
kubectl get application forgejo-server -n argocd
kubectl get application forgejo-runner -n argocd

# Verify Forgejo server pods are running
kubectl get pods -n gitea

# Check PostgreSQL cluster status
kubectl get cluster -n gitea

# Verify Forgejo runners are active
kubectl get pods -n gitea -l app=forgejo-runner

# Verify ingress configuration
kubectl get ingress -n gitea

Access the Forgejo web interface at https://{DOMAIN_GITEA}.

Architecture

Component Architecture

The Forgejo stack consists of:

Forgejo Server:

• Web application for Git repository management
• API server for Git operations and CI/CD orchestration
• Issue tracker and project management interface
• Container registry for Docker images
• Artifact storage via MinIO object storage

Forgejo Runners:

• 3-replica runner deployment for parallel job execution
• Docker-in-Docker (DinD) architecture for containerized builds
• Runner image: code.forgejo.org/forgejo/runner:6.4.0
• Build container: docker:28.0.4-dind
• Supports GitHub Actions-compatible workflows

Storage Architecture:

• 200Gi persistent volume for Git repositories (GPSSD storage)
• OTC S3 object storage for LFS objects and artifacts
• Encrypted volumes using KMS key integration
• S3-compatible backup storage (100GB)

Networking:

• SSH LoadBalancer service on port 32222 for Git operations
• HTTPS ingress with TLS termination for web interface
• Internal service communication via ClusterIP

Configuration

Forgejo Server Configuration

The Forgejo server is configured through Helm values in stacks/forgejo/forgejo-server/values.yaml:

Application Settings:

• FORGEJO_IMAGE_TAG: Forgejo container image version
• Application name: "EDP"
• Slogan: "Build your thing in minutes"
• User registration: Disabled by default
• Email notifications: Enabled

Storage Configuration:

persistence:
  size: 200Gi
  storageClass: csi-disk
  annotations:
    everest.io/crypt-key-id: "{KMS_KEY_ID}"
    everest.io/disk-volume-type: GPSSD

Database Configuration: Database credentials are sourced from Kubernetes secrets:

• POSTGRES_HOST: PostgreSQL hostname
• POSTGRES_DB: Database name
• POSTGRES_USER: Database username
• POSTGRES_PASSWORD: Database password
• SSL verification enabled

Object Storage:

• Endpoint: obs.eu-de.otc.t-systems.com
• Credentials from gitea/forgejo-cloud-credentials secret
• Used for artifacts, LFS objects, and backups

External Services:

• Redis for caching and session management
• Elasticsearch for issue indexing
• SMTP for email notifications

SSH Configuration:

service:
  ssh:
    type: LoadBalancer
    port: 32222

Forgejo Runner Configuration

Defined in stacks/forgejo/forgejo-runner/dind-docker.yaml:

Deployment Specification:

• 3 replicas for parallel execution
• Runner version: 6.4.0
• Docker DinD version: 28.0.4

Runner Registration:

• Offline registration using secret token
• Instance URL from configuration
• Predefined labels for Ubuntu 22.04 and latest

Container Configuration:

runner:
  image: code.forgejo.org/forgejo/runner:6.4.0
  privileged: true
  securityContext:
    runAsUser: 0
    allowPrivilegeEscalation: true

dind:
  image: docker:28.0.4-dind
  privileged: true
  tlsCertDir: /certs

Volume Management:

• Docker certificates volume for TLS communication
• Runner data volume for registration and configuration
• Shared socket for container communication

ArgoCD Application Configuration

Server Application (template/stacks/forgejo/forgejo-server.yaml):

• Name: forgejo-server
• Namespace: gitea
• Helm chart v12.0.0 from https://code.forgejo.org/forgejo-helm/forgejo-helm.git
• Automated self-healing enabled
• Values from stacks-instances repository

Runner Application (template/stacks/forgejo/forgejo-runner.yaml):

• Name: forgejo-runner
• Namespace: argocd
• Deployment manifests from stacks-instances repository
• Automated sync with unlimited retries

Usage Examples

Creating Your First Repository

After deployment, create and use Git repositories:

1. Access Forgejo Interface

   open https://${DOMAIN_GITEA}
   

2. Create a New Repository

   • Click "+" icon in top right
   • Select "New Repository"
   • Enter repository name and description
   • Choose visibility (public/private)
   • Initialize with README if desired

3. Clone and Push Code

   # Clone the repository
   git clone https://${DOMAIN_GITEA}/myorg/myrepo.git
   cd myrepo
   
   # Add your code
   echo "# My Project" > README.md
   git add README.md
   git commit -m "Initial commit"
   
   # Push to Forgejo
   git push origin main
   

Setting Up CI/CD with Forgejo Actions

Create automated workflows using Forgejo Actions:

1. Create Workflow File

   mkdir -p .forgejo/workflows
   cat > .forgejo/workflows/build.yaml << 'EOF'
   name: Build and Test
   
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   
   jobs:
     build:
       runs-on: ubuntu-22.04
       steps:
         - name: Checkout code
           uses: actions/checkout@v4
   
         - name: Set up Go
           uses: actions/setup-go@v4
           with:
             go-version: '1.21'
   
         - name: Build
           run: go build -v ./...
   
         - name: Test
           run: go test -v ./...
   EOF
   

2. Commit and Push Workflow

   git add .forgejo/workflows/build.yaml
   git commit -m "Add CI/CD workflow"
   git push origin main
   

3. Monitor Workflow Execution

   • Navigate to repository in Forgejo web interface
   • Click "Actions" tab
   • View workflow runs and logs

Building and Publishing Container Images

Use Forgejo to build and store Docker images:

# .forgejo/workflows/docker.yaml
name: Build Container Image

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build image
        run: |
          docker build -t forgejo.${DOMAIN_GITEA}/myorg/myapp:${GITHUB_REF_NAME} .

      - name: Login to registry
        run: |
          echo "${{ secrets.REGISTRY_PASSWORD }}" | \
          docker login forgejo.${DOMAIN_GITEA} -u "${{ secrets.REGISTRY_USER }}" --password-stdin

      - name: Push image
        run: |
          docker push forgejo.${DOMAIN_GITEA}/myorg/myapp:${GITHUB_REF_NAME}

Using SSH for Git Operations

Configure SSH access for Git operations:

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add public key to Forgejo
# Navigate to: Settings -> SSH / GPG Keys -> Add Key

# Configure SSH host
cat >> ~/.ssh/config << EOF
Host forgejo.${DOMAIN_GITEA}
  Port 32222
  User git
EOF

# Clone repository via SSH
git clone ssh://git@forgejo.${DOMAIN_GITEA}:32222/myorg/myrepo.git

Integration Points

• Core Stack: Depends on ArgoCD for deployment orchestration and CloudNativePG operator for database management
• OTC Stack: Requires ingress-nginx controller and cert-manager for external access and TLS
• Coder Stack: Development workspaces can clone repositories and trigger CI/CD workflows
• Observability Stack: Prometheus metrics collection enabled via ServiceMonitor
• Dex (SSO): Can be configured for centralized authentication integration

Troubleshooting

Forgejo Server Not Starting

Problem: Forgejo server pods remain in Pending or CrashLoopBackOff state

Solution:

1. Check PostgreSQL cluster status:

   kubectl get cluster -n gitea
   kubectl describe cluster -n gitea
   

2. Verify database credentials:

   kubectl get secret -n gitea | grep postgres
   

3. Check Forgejo server logs:

   kubectl logs -n gitea -l app=forgejo
   

4. Verify MinIO connectivity:

   kubectl get secret minio-credential -n gitea
   kubectl logs -n gitea -l app=forgejo | grep -i minio
   

Cannot Access Forgejo Web Interface

Problem: Forgejo web interface is not accessible at configured URL

Solution:

1. Verify ingress configuration:

   kubectl get ingress -n gitea
   kubectl describe ingress -n gitea
   

2. Check TLS certificate status:

   kubectl get certificate -n gitea
   kubectl describe certificate -n gitea
   

3. Verify DNS resolution:

   nslookup forgejo.${DOMAIN_GITEA}
   

4. Test service connectivity:

   kubectl port-forward -n gitea svc/forgejo-http 3000:3000
   curl http://localhost:3000
   

Git Operations Fail Over SSH

Problem: Cannot clone or push repositories via SSH

Solution:

1. Verify SSH service is exposed:

   kubectl get svc -n gitea -l app=forgejo
   

2. Check LoadBalancer external IP:

   kubectl get svc -n gitea forgejo-ssh -o wide
   

3. Test SSH connectivity:

   ssh -T -p 32222 git@${DOMAIN_GITEA}
   

4. Verify SSH public key is added to Forgejo account

Forgejo Runners Not Executing Jobs

Problem: CI/CD workflows remain queued or fail to execute

Solution:

1. Check runner pod status:

   kubectl get pods -n gitea -l app=forgejo-runner
   kubectl logs -n gitea -l app=forgejo-runner
   

2. Verify runner registration:

   kubectl exec -n gitea -it deployment/forgejo-runner -- \
     forgejo-runner status
   

3. Check Docker-in-Docker daemon:

   kubectl logs -n gitea -l app=forgejo-runner -c dind
   

4. Verify runner token secret exists:

   kubectl get secret -n gitea | grep runner
   

5. Check Forgejo server can communicate with runners:

   kubectl logs -n gitea -l app=forgejo | grep -i runner
   

Database Connection Errors

Problem: Forgejo cannot connect to PostgreSQL database

Solution:

1. Verify PostgreSQL cluster health:

   kubectl get pods -n gitea -l cnpg.io/cluster
   kubectl logs -n gitea -l cnpg.io/cluster
   

2. Test database connection:

   kubectl exec -n gitea -it <postgres-pod> -- \
     psql -U postgres -c "\l"
   

3. Verify database credentials secret:

   kubectl get secret -n gitea -o yaml | grep POSTGRES
   

4. Check database connection from Forgejo pod:

   kubectl exec -n gitea -it <forgejo-pod> -- \
     nc -zv <postgres-host> 5432
   

Storage Issues

Problem: Repository pushes fail or object storage errors occur

Solution:

1. Check PVC status and capacity:

   kubectl get pvc -n gitea
   kubectl describe pvc -n gitea
   

2. Verify MinIO credentials and connectivity:

   kubectl get secret minio-credential -n gitea
   kubectl logs -n gitea -l app=forgejo | grep -i "s3\|minio"
   

3. Check available storage space:

   kubectl exec -n gitea -it <forgejo-pod> -- df -h
   

4. Review storage class configuration:

   kubectl get storageclass csi-disk -o yaml
   

Additional Resources

• Forgejo Documentation
• Forgejo Actions User Guide
• Forgejo Helm Chart Documentation
• Forgejo Runner Documentation
• CloudNativePG Documentation
• ArgoCD Documentation