website-and-documentation/content/en/docs/components/forgejo/actions/runner-orchestration.md

title	linkTitle	weight	description
Runner Orchestration	Runner Orchestration	30	GARM

{{% alert title="Draft" color="warning" %}} Editorial Status: This page is currently being developed.

• Jira Ticket: TICKET-XXX
• Assignee: [Name or Team]
• Status: Draft
• Last Updated: YYYY-MM-DD
• TODO:
  • Add detailed component description
  • Include usage examples and code samples
  • Add architecture diagrams
  • Review and finalize content {{% /alert %}}

Overview

[Detailed description of the component - what it is, what it does, and why it exists]

Key Features

• [Feature 1]
• [Feature 2]
• [Feature 3]

Purpose in EDP

[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]

Repository

Code: [Link to source code repository]

Documentation: [Link to component-specific documentation]

Getting Started

Prerequisites

• [Prerequisite 1]
• [Prerequisite 2]

Quick Start

[Step-by-step guide to get started with this component]

1. [Step 1]
2. [Step 2]
3. [Step 3]

Verification

[How to verify the component is working correctly]

Usage Examples

[Use Case 1]

[Example with code/commands showing common use case]

# Example commands

[Use Case 2]

[Another common scenario]

Integration Points

• [Component A]: [How it integrates]
• [Component B]: [How it integrates]
• [Component C]: [How it integrates]

Architecture

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)

Configuration

[Key configuration options and how to set them]

Troubleshooting

[Common Issue 1]

Problem: [Description]

Solution: [How to fix]

[Common Issue 2]

Problem: [Description]

Solution: [How to fix]

Status

Maturity: [Production / Beta / Experimental]

Additional Resources

• [Link to external documentation]
• [Link to community resources]
• [Link to related components]

Documentation Notes

[Instructions for team members filling in this documentation - remove this section once complete]