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.1 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)

These KPIs measure the effectiveness of the Forgejo setup and quantify our strategic commitment to the Forgejo community.

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)