# actions/runner architecture

> Architecture diagram of the GitHub repository actions/runner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/actions/runner
- Repository: https://github.com/actions/runner

## Overview

##### Main Components

a. Core Runner Components:
- Runner Service/Daemon (Runner.Service)
- Runner Listener (Runner.Listener)
- Worker (Runner.Worker)
- Plugin Host (Runner.PluginHost)
- Common Infrastructure (Runner.Common)

b. External Integration Points:
- GitHub Actions Service
- Container Services (Docker)
- Source Control (Git)
- Artifact Storage
- Runner Registration System

##### Key Architectural Patterns to Highlight

a. Message-Based Architecture:
- Message listener pattern
- Job dispatch flow
- Demonstrate the broker message system

b. Plugin Architecture:
- Repository plugins
- Artifact plugins
- Custom action plugins

c. Container Management:
- Docker integration
- Container hooks
- Container operations

##### Specific Implementation Details

**┌─ GitHub Actions Service Layer ─────────────────────┐**
- Job Distribution                                 │
- Authentication/Authorization                     │
- Runner Management                               │
- ┬───────────────────────────────┘

**┌─ Runner Service Layer ──────────────────────────┐**
- Runner.Listener                               │
- Message Processing                            │
- Job Dispatch                                  │
- Self-Update Management                        │
- ┬──────────────────────────────┘

**┌─ Execution Layer ────────────────────────────────┐**
- Runner.Worker                                  │
- Action Execution                               │
- Step Processing                                │
- Container Management                           │
- ┬──────────────────────────────┘

**┌─ Plugin Layer ──────────────────────────────────┐**
- Repository Plugins                            │
- Artifact Plugins                             │
- Custom Action Support                        │
- ┬──────────────────────────────┘

**┌─ Infrastructure Layer ────────────────────────────┐**
- Runner.Common                                   │
- Authentication                                  │
- Configuration                                   │
- Logging                                         │
- ┘

##### Flow Indicators

- Double lines: High-bandwidth data flow

##### Additional Elements

Specific callouts for:
- Security boundaries
- Authentication points
- Scaling components
- Error handling paths
- Update mechanisms

##### Implementation Details

- The separation between listener and worker processes
- The plugin architecture for extensibility
- The container execution environment
- The job execution pipeline
- The self-update mechanism

##### Critical Paths

Highlight:
- Job acquisition flow
- Action execution pipeline
- Plugin loading and execution
- Container lifecycle management
- Artifact upload/download paths

This system design should be created using a tool that supports:
- Nested components
- Relationship lines with different styles
- Text annotations
- Grouping of related components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph GitHub["GitHub Actions Service Layer"]
        GH_JOBS["Job Distribution"]
        GH_AUTH["Authentication/Authorization"]
        GH_RUNNER["Runner Management"]
    end

    subgraph RunnerService["Runner Service Layer"]
        RL["Runner Listener"]:::listener
        MP["Message Processing"]:::msg
        JD["Job Dispatch"]:::dispatch
        SU["Self-Update Management"]:::update
    end

    subgraph Execution["Execution Layer"]
        RW["Worker"]:::worker
        AE["Action Execution"]:::action
        SP["Step Processing"]
        CM["Container Management"]:::container
    end

    subgraph Plugins["Plugin Layer"]
        PH["Plugin Host"]:::plugin
        RP["Repository Plugins"]:::plugin
        AP["Artifact Plugins"]:::plugin
        CA["Custom Action Support"]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        RC["Runner Common"]:::common
        AUTH["Authentication"]:::auth
        CONF["Configuration"]
        LOG["Logging"]
    end

    %% Connections between layers
    GH_JOBS --> RL
    GH_AUTH --> AUTH
    GH_RUNNER --> RL

    RL --> MP
    MP --> JD
    JD --> RW
    SU --> RL

    RW --> AE
    RW --> SP
    RW --> CM

    AE --> PH
    PH --> RP
    PH --> AP
    PH --> CA

    RC --> AUTH
    RC --> CONF
    RC --> LOG

    %% Click events for component mapping
    click RL "https://github.com/actions/runner/blob/main/src/Runner.Listener/MessageListener.cs"
    click MP "https://github.com/actions/runner/blob/main/src/Runner.Listener/BrokerMessageListener.cs"
    click JD "https://github.com/actions/runner/blob/main/src/Runner.Listener/JobDispatcher.cs"
    click SU "https://github.com/actions/runner/blob/main/src/Runner.Listener/SelfUpdaterV2.cs"
    click RW "https://github.com/actions/runner/blob/main/src/Runner.Worker/Worker.cs"
    click AE "https://github.com/actions/runner/blob/main/src/Runner.Worker/ActionRunner.cs"
    click CM "https://github.com/actions/runner/tree/main/src/Runner.Worker/Container"
    click PH "https://github.com/actions/runner/blob/main/src/Runner.PluginHost/Program.cs"
    click RP "https://github.com/actions/runner/tree/main/src/Runner.Plugins/Repository"
    click RC "https://github.com/actions/runner/blob/main/src/Runner.Common"
    click AUTH "https://github.com/actions/runner/blob/main/src/Runner.Common/RunnerServer.cs"

    %% Styling
    classDef listener fill:#2196F3,stroke:#1565C0,color:white
    classDef msg fill:#4CAF50,stroke:#2E7D32,color:white
    classDef dispatch fill:#FF9800,stroke:#EF6C00,color:white
    classDef update fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef worker fill:#F44336,stroke:#C62828,color:white
    classDef action fill:#3F51B5,stroke:#283593,color:white
    classDef container fill:#FF5722,stroke:#D84315,color:white
    classDef plugin fill:#FFEB3B,stroke:#FBC02D,color:black
    classDef common fill:#607D8B,stroke:#37474F,color:white
    classDef auth fill:#795548,stroke:#4E342E,color:white
```
