Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity
website-and-documentation/content/en/docs/components/forgejo/forgejo.md

8 KiB
Raw Blame History

title date description tags categories mermaid
Edge Developer Platform: Forgejo Integration & GARM Extension 2025-11-19 Technical report on the implementation of the Edge Developer Platform (EDP) using Forgejo, featuring GARM integration for ephemeral CI/CD runners and upstream open-source contributions.
Forgejo
GARM
CI/CD
OSS
Architecture
Project Report
Workpackage Results
true

1. Project Identity & Governance

1.1 Project Scope

The internal service is officially designated as the Edge Developer Platform (EDP). It is hosted at edp.buildth.ing. The domain selection followed a democratic team process to establish a unique identity distinct from standard corporate naming conventions.

Access Model: The platform operates on a hybrid visibility model:

  • Public Access: The DEVFW-CICD organization is publicly accessible, fostering transparency.
  • Private Access: Sensitive development occurs in restricted organizations (e.g., DEVFW).
  • User Base: Primary users include the internal development team, with friendly user access granted to the IPCEI team and MMS BT.

1.2 Strategic Selection & Governance

The decision to utilize Forgejo as the core self-hosted Git service was driven by specific strategic requirements:

  • EU-Based Stewardship: Forgejo is stewarded by Codeberg e.V., a non-profit organization based in Berlin, Germany. This alignment ensures compliance with GDPR and data sovereignty requirements, placing governance under EU jurisdiction rather than US tech entities.
  • License Protection (GPL v3+): Unlike "Open Core" models, Forgejo uses a copyleft license. This legally protects our custom extensions (such as GARM support) from being appropriated into proprietary software, ensuring the ecosystem remains open.
  • Open Source Strategy: The platform aligns with the "Public Money, Public Code" philosophy, mandating that funded developments are returned to the community.

2. Technical Architecture & Deployment

2.1 Infrastructure Stack

The platform is hosted on the Open Telekom Cloud (OTC). The infrastructure adheres to Infrastructure-as-Code (IaC) principles.

  • Deployment Method: The official Forgejo Helm Chart is deployed via ArgoCD.
  • Infrastructure Provisioning: Terraform is used to provision all underlying OTC services, including:
    • Container Orchestration: CCE (Cloud Container Engine): Kubernetes
    • Database: RDS (Distributed Cache Service): PostgreSQL
    • Caching: DCS (Distributed Cache Service): Redis
    • Object Storage: OBS (Object Storage Service, S3-compatible): for user data (avatars, attachments).
    • Search: CSS (Cloud Search Service): Elasticsearch

2.2 The "Self-Replicating" Pipeline

A key architectural feature is the ability of the platform to maintain itself. A Forgejo Action can trigger the deployment script, which runs Terraform and syncs ArgoCD, effectively allowing "Forgejo to create/update Forgejo."

graph TD
    subgraph "Open Telekom Cloud (OTC)"
        subgraph "Control Plane"
            Dev[DevOps Engineer] -->|Triggers| Pipeline[Deployment Pipeline]
            Pipeline -->|Executes| TF[Terraform]
        end
        
        subgraph "Provisioned Infrastructure"
            TF -->|Provisions| CCE[(CCE K8s Cluster)]
            TF -->|Provisions| RDS[(RDS PostgreSQL)]
            TF -->|Provisions| Redis[(DCS Redis)]
            TF -->|Provisions| S3[(OBS S3 Bucket)]
            TF -->|Provisions| CSS[(CSS Elasticsearch)]
        end
        
        subgraph "Application Layer (on CCE K8s)"
            Pipeline -->|Helm Chart| Argo[ArgoCD]
            Argo -->|Deploys| ForgejoApp[Forgejo]
        end
        
        CCE -- Runs --> Argo
        CCE -- Runs --> ForgejoApp
        ForgejoApp -->|Connects| RDS
        ForgejoApp -->|Connects| Redis
        ForgejoApp -->|Connects| S3
        ForgejoApp -->|Connects| CSS
    end

2.3 Migration History

The initial environment was a manual setup on the Open Sovereign Cloud (OSC). Once the automation stack (Terraform/ArgoCD) was matured, the platform was migrated to the current OTC environment.

3. Application Extensions & GARM Integration

3.1 Core Functionality

Beyond standard Git versioning, the platform utilizes:

  • Releases: Hosting binaries for software distribution (e.g., Edge Connect CLI).
  • CI/CD: Extensive pipeline usage for build, test, and deployment automation.
  • Note on Issues: While initially used, issue tracking was migrated to JIRA to align with the broader IPCEI program standards.

3.2 GARM (Git-based Actions Runner Manager)

The primary technical innovation was the integration of GARM to enable ephemeral, scalable runners. This required extending Forgejo's capabilities to support GitHub-compatible runner registration and webhook events.

Workflow Architecture:

  1. Event: A workflow event occurs in Forgejo.
  2. Trigger: A webhook notifies GARM.
  3. Provisioning: GARM spins up a fresh, ephemeral runner.
  4. Execution: The runner registers via the API, executes the job, and is terminated immediately after, ensuring a clean build environment.
sequenceDiagram
    participant User
    participant Forgejo
    participant GARM
    participant Runner as Ephemeral Runner
    
    User->>Forgejo: Push Code / Trigger Event
    Forgejo->>GARM: Webhook Event (Workflow Dispatch)
    GARM->>Forgejo: Register Runner (via API)
    GARM->>Runner: Spin up Instance
    Runner->>Forgejo: Request Job
    Forgejo->>Runner: Send Job Payload
    Runner->>Runner: Execute Steps
    Runner->>Forgejo: Report Status
    GARM->>Runner: Terminate (Ephemeral)

4. Development Methodology & Contributions

4.1 Workflow

  • Branching Strategy: Trunk-based development was utilized to ensure rapid integration.
  • Collaboration: The team adopted Mob Programming. This practice proved essential for knowledge sharing and onboarding junior developers, creating a resilient and high-intensity learning environment.
  • Versions: The platform evolved from Forgejo v7/8 to the current v11.0.3-edp1. An upgrade is pending to leverage the latest upstream GARM features.

4.2 Open Source Contributions

We actively contributed our extensions back to the upstream Forgejo project on Codeberg.org.

Key Pull Requests:

Artifact Caching (Pull-Through Proxy): We implemented a feature allowing Forgejo to act as a pull-through proxy for remote container registries, optimizing bandwidth and build speeds.

5. Key Performance Indicators (KPIs)

KPI Description Target / Benchmark
Deployment Frequency Frequency of successful pipeline executions. High (Daily/On-demand)
Artifact Cache Hit Rate Percentage of build requests served by the local Forgejo proxy. > 90% (Reduced external traffic)
Upstream Contribution Percentage of GARM-related features contributed back to Codeberg. 100% (No vendor lock-in)
PR Resolution Time Average time for upstream community review and merge. < 14 days (Healthy collaboration)