GitHub Actions Architecture

GitHub Actions is GitHub's native CI/CD platform that enables developers to automate software workflows directly from their repositories. Since its general availability in November 2019, it has become one of the most widely adopted automation platforms in the software industry.

At its core, GitHub Actions is built on an event-driven architecture: something happens in your repository (a push, a pull request, a scheduled time), and the system responds by executing a predefined sequence of tasks. Understanding the architecture is critical for designing efficient, secure, and scalable pipelines.

Key Architectural Components

The architecture comprises several layered components, each with a distinct role:

The entire pipeline — from event to result — traverses these layers sequentially, with each layer adding orchestration logic or compute capability 2.

Footnotes

1. GitHub Docs: Understanding GitHub Actions — Official documentation on GitHub Actions core concepts and architecture. ↩

2. GitHub Blog: GitHub Actions — Built by developers, for developers — Architectural overview and design philosophy of GitHub Actions. ↩

The Event Layer: How Workflows Are Triggered

The event system is the entry point into GitHub Actions. Events are categorized into several types:

• Webhook events — triggered by GitHub activity (push, pull_request, issues, release)
• Scheduled events — cron-based scheduling via the schedule trigger
• Manual events — workflow_dispatch and repository_dispatch for on-demand execution
• External events — triggered via the GitHub API or third-party integrations

When an event occurs, GitHub creates an event payload, which is delivered to the workflow engine. The GITHUB_SHA and GITHUB_REF environment variables are set based on the event's git reference, anchoring the workflow to a specific commit state .

The Workflow Engine: YAML Parsing and Orchestration

The workflow engine is the brain of GitHub Actions. It:

1. Parses the .github/workflows/*.yml files from the target commit
2. Validates syntax and resolves expressions (${{ }} syntax)
3. Evaluates conditionals (if:, needs:, jobs.<job_id>.condition)
4. Computes the matrix strategy — dynamically generating job instances from strategy.matrix
5. Schedules jobs respecting needs: dependencies, forming a DAG

The engine uses the needs keyword to construct a DAG of jobs. A job only starts when all its dependencies succeed (unless if: always() is used). This graph-based scheduling is what allows fan-out and fan-in parallelism .

Footnotes

1. GitHub Docs: Workflow Syntax for GitHub Actions — Complete reference for workflow YAML syntax, expressions, contexts, and job dependencies. ↩ ↩²

Runner Architecture: The Compute Layer

The runner is arguably the most critical architectural component. It is the Runner Application — an open-source Go program that polls GitHub's API for job assignments and executes them.

GitHub-Hosted Runners

GitHub-hosted runners are ephemeral virtual machines provisioned by GitHub from a shared pool:

The ephemeral nature is a key security property: since each job gets a clean machine, there is no risk of cross-job contamination. However, this also means no persistent state — everything must be explicitly cached or uploaded as an artifact .

Self-Hosted Runners

Self-hosted runners are machines you provision and manage yourself. They run the same actions/runner application but connect to GitHub via a persistent poll loop:

Self-hosted runners are persistent — the machine is not destroyed between jobs. This enables caching at the machine level (e.g., Docker image layers, package caches), but introduces security considerations since malicious workflows could access previous job data .

Footnotes

1. GitHub Docs: About GitHub-Hosted Runners — Specifications, software, and lifecycle of GitHub-hosted runners. ↩

2. GitHub Docs: Self-Hosted Runners Security — Security hardening guide for self-hosted runners. ↩

Actions: The Reusable Execution Units

An action is the smallest composable unit in GitHub Actions. Actions come in three architectural forms:

Action Metadata: action.yml

Every action must define an action.yml (or action.yaml) metadata file:

1name: "My Custom Action"
2description: "Does something useful"
3inputs:
4  file-path:
5    description: "Path to file"
6    required: true
7outputs:
8  result:
9    description: "The output value"
10    value: ${{ steps.compute.outputs.value }}
11runs:
12  using: "node16"        # or "docker" or "composite"
13  main: "dist/index.js"  # entry point

The action metadata defines the interface contract — inputs the action accepts and outputs it produces. This contract is resolved by the workflow engine before the runner executes the action, enabling type-safe wiring between steps .

Security Architecture

GitHub Actions' security model is built on several layers:

1. GITHUB_TOKEN — an installation-scoped token automatically created for each workflow run. It has scoped permissions defined by permissions: in the workflow (read, write, none).

2. **OpenID Connect (OIDC) — allows workflows to authenticate with cloud providers (AWS, Azure, GCP) without storing long-lived secrets.

3. Environment Protection Rules — required reviewers, wait timers, and branch restrictions that gate deployments.

4. Runner Group Access Control — restrict which repositories/workflows can use self-hosted runners .

Footnotes

1. GitHub Docs: Workflow Syntax for GitHub Actions — Complete reference for workflow YAML syntax, expressions, contexts, and job dependencies. ↩

2. GitHub Docs: Self-Hosted Runners Security — Security hardening guide for self-hosted runners. ↩

Context and Expression Architecture

GitHub Actions provides a rich context system that exposes runtime data to workflow expressions. Contexts are resolved at different stages of the pipeline:

The ${{ }} expression syntax supports:

• Comparison operators: ==, !=, <, >, <=, >=
• Logical operators: &&, ||, !
• Functions: contains(), startsWith(), endsWith(), format(), hashFiles(), toJson(), fromJSON()

Importantly, secrets are always masked in logs — the runner replaces secret values with *** in output streams. The $GITHUB_TOKEN is also revoked and expired after the workflow run completes 2.

Artifact and Cache Architecture

• Artifacts are stored in GitHub-managed blob storage with a retention period (default 90 days). They are the primary mechanism for passing data between jobs within a workflow or across workflow runs.
• Caches are keyed by scope (branch + repository) and a user-defined key. They use an LRU eviction policy with a total limit (10 GB per repository on free plans). Caches are read-write within the same scope and read-only in child branches .

Footnotes

1. GitHub Docs: Workflow Syntax for GitHub Actions — Complete reference for workflow YAML syntax, expressions, contexts, and job dependencies. ↩

2. GitHub Docs: Contexts and Expressions — Reference for expression syntax, operators, and functions in GitHub Actions. ↩

3. GitHub Docs: About GitHub-Hosted Runners — Specifications, software, and lifecycle of GitHub-hosted runners. ↩