---
title: "Forgejo"
linkTitle: "Forgejo"
weight: 30
description: >
  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](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo)

**Documentation**:
* [Forgejo Official Documentation](https://forgejo.org/docs/latest/)
* [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)
* [Forgejo Helm Chart Repository](https://code.forgejo.org/forgejo-helm/forgejo-helm)

## 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](https://edp.buildth.ing/DevFW/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](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml)
   - 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:

```bash
# 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**:
```yaml
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**:
```yaml
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**:
```yaml
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**
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   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:

```yaml
# .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:

```bash
# 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:
   ```bash
   kubectl get cluster -n gitea
   kubectl describe cluster -n gitea
   ```

2. Verify database credentials:
   ```bash
   kubectl get secret -n gitea | grep postgres
   ```

3. Check Forgejo server logs:
   ```bash
   kubectl logs -n gitea -l app=forgejo
   ```

4. Verify MinIO connectivity:
   ```bash
   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:
   ```bash
   kubectl get ingress -n gitea
   kubectl describe ingress -n gitea
   ```

2. Check TLS certificate status:
   ```bash
   kubectl get certificate -n gitea
   kubectl describe certificate -n gitea
   ```

3. Verify DNS resolution:
   ```bash
   nslookup forgejo.${DOMAIN_GITEA}
   ```

4. Test service connectivity:
   ```bash
   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:
   ```bash
   kubectl get svc -n gitea -l app=forgejo
   ```

2. Check LoadBalancer external IP:
   ```bash
   kubectl get svc -n gitea forgejo-ssh -o wide
   ```

3. Test SSH connectivity:
   ```bash
   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:
   ```bash
   kubectl get pods -n gitea -l app=forgejo-runner
   kubectl logs -n gitea -l app=forgejo-runner
   ```

2. Verify runner registration:
   ```bash
   kubectl exec -n gitea -it deployment/forgejo-runner -- \
     forgejo-runner status
   ```

3. Check Docker-in-Docker daemon:
   ```bash
   kubectl logs -n gitea -l app=forgejo-runner -c dind
   ```

4. Verify runner token secret exists:
   ```bash
   kubectl get secret -n gitea | grep runner
   ```

5. Check Forgejo server can communicate with runners:
   ```bash
   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:
   ```bash
   kubectl get pods -n gitea -l cnpg.io/cluster
   kubectl logs -n gitea -l cnpg.io/cluster
   ```

2. Test database connection:
   ```bash
   kubectl exec -n gitea -it <postgres-pod> -- \
     psql -U postgres -c "\l"
   ```

3. Verify database credentials secret:
   ```bash
   kubectl get secret -n gitea -o yaml | grep POSTGRES
   ```

4. Check database connection from Forgejo pod:
   ```bash
   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:
   ```bash
   kubectl get pvc -n gitea
   kubectl describe pvc -n gitea
   ```

2. Verify MinIO credentials and connectivity:
   ```bash
   kubectl get secret minio-credential -n gitea
   kubectl logs -n gitea -l app=forgejo | grep -i "s3\|minio"
   ```

3. Check available storage space:
   ```bash
   kubectl exec -n gitea -it <forgejo-pod> -- df -h
   ```

4. Review storage class configuration:
   ```bash
   kubectl get storageclass csi-disk -o yaml
   ```

## Additional Resources

* [Forgejo Documentation](https://forgejo.org/docs/latest/)
* [Forgejo Actions User Guide](https://forgejo.org/docs/latest/user/actions/)
* [Forgejo Helm Chart Documentation](https://code.forgejo.org/forgejo-helm/forgejo-helm)
* [Forgejo Runner Documentation](https://code.forgejo.org/forgejo/runner)
* [CloudNativePG Documentation](https://cloudnative-pg.io/)
* [ArgoCD Documentation](https://argo-cd.readthedocs.io/)