GitHub Actions

GitHub Actions#

GitHub Actions is GitHub’s in-platform CI/CD. Workflows are YAML files in .github/workflows/; runners execute jobs on GitHub- hosted or operator-hosted machines; a marketplace of community actions cuts the boilerplate. The operator’s default when the code already lives in GitHub.

Architecture#

  • Workflow: a YAML file in .github/workflows/, triggered by one or more events.

  • Job: a set of steps that run on a single runner.

  • Step: a shell command or a published action invocation.

  • Action: a reusable unit (Docker container, JavaScript function, or composite action) published on the marketplace or in another repository.

  • Runner: a machine that executes jobs. GitHub-hosted (ubuntu-latest, macos-latest, windows-latest) or self-hosted (operator-owned VMs, Kubernetes via Actions Runner Controller, or bare metal).

Workflow shape#

# .github/workflows/ci.yaml
name: ci
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  id-token: write                          # OIDC for cloud auth

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ['20', '22']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: pnpm
      - run: corepack enable
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

  build-push:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}

Triggers#

Event

Use

push / pull_request

The defaults for CI.

schedule

Cron. Note: scheduled runs trigger from the default branch only.

workflow_dispatch

Manual trigger with optional inputs.

repository_dispatch

Programmatic trigger via the API.

workflow_run

Trigger off another workflow’s completion.

release, issues, deployment, etc.

Any GitHub event the operator wants to react to.

Secrets and auth#

  • Repository / environment / organization secrets in the UI; available as ${{ secrets.NAME }}.

  • OIDC for cloud auth without static credentials. Mint a short-lived token from the runner; cloud trusts GitHub’s issuer.

  • GitHub App tokens when the workflow needs cross-repo access; use a custom app rather than an org-wide PAT.

Runners#

Runner

Detail

GitHub-hosted

Pre-built images with the toolchain installed. Free minutes per month on public repos; paid on private.

Self-hosted

Operator-owned. Required for ARM, GPU, on-prem networks, or large concurrency.

ARC (Actions Runner Controller)

Kubernetes-native, ephemeral runners that scale on demand inside the operator’s cluster.

When to pick GitHub Actions#

  • The repo lives on GitHub and the operator wants one fewer tool to integrate.

  • Marketplace ecosystem covers most of the steps the operator needs out of the box.

  • OIDC into AWS / GCP / Azure removes the static-credential problem.

When to pick something else#

  • Multi-repo or polyrepo build graphs at scale (Buildkite, Bazel + remote execution, Earthly).

  • Self-hosted-only environments where introducing the GitHub control plane is not allowed.

  • Teams whose code lives elsewhere (GitLab, Bitbucket).

References#

Contents