Hands-on: worked through with sharifndlovu123/github-actions-course, the companion repo for the DevOps Directive "GitHub Actions: Beginner to Pro" course. The basics are in 2. GitHub Actions; this note goes deeper.

What each topic is for

Authoring your own actions and testing workflows locally: Authoring and Testing GitHub Actions.

Core Features

flowchart TB
    E[Event: push, pull_request, schedule, workflow_dispatch] --> W[Workflow: YAML file]
    W --> J1[Job A]
    W --> J2[Job B needs: A]
    J1 --> S1[Step: run shell]
    J1 --> S2[Step: uses action]

• A workflow reacts to events; it contains jobs that run in parallel unless needs: orders them
• A step is either a shell command (run:, bash by default on Linux, also Python and others via shell:) or an action (uses:)
• Each job gets a fresh runner, so nothing carries over between jobs unless you pass it explicitly

Triggers and filters

on:
  push:
    branches: [main]
    paths: ["src/**", "!src/**/*.md"]     # only run when matching files change
    tags: ["v*"]
  pull_request:
    paths-ignore: ["docs/**"]
  workflow_dispatch:                       # manual run button
    inputs:
      env: { type: choice, options: [staging, production] }

Path and branch filters are the cheapest way to do less: a docs-only change should not run the full test suite.

Variables and scope

Variables can be set at three levels, and the closest one wins:

env:                       # workflow level
  LEVEL: workflow
jobs:
  demo:
    runs-on: ubuntu-latest
    env:
      LEVEL: job           # job level
    steps:
      - run: echo "$LEVEL"           # job
      - env:
          LEVEL: step      # step level
        run: echo "$LEVEL"           # step

Use vars.NAME for non-sensitive configuration and secrets.NAME for sensitive values. Both can be defined on the repository or on an environment (which can also require reviewers).

Passing data

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.v.outputs.version }}
    steps:
      - id: v
        run: echo "version=1.4.2" >> "$GITHUB_OUTPUT"
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.version }}"

Runners

Avoid emulation (QEMU) where you can; use native ARM and x86 runners for each architecture. Never attach self-hosted runners to public repositories that accept fork pull requests.

Artifacts and Caching

- uses: actions/cache@<sha>        # pin to a commit SHA
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-

• The key should change when the dependencies change (hash the lock file)
• restore-keys allow a partial hit from an older cache
• Measure cache hit rate and job time before and after; a cache that never hits only adds work
• Prune unused caches and artifacts; set retention-days

Permissions and Cloud Authentication

The automatic GITHUB_TOKEN is scoped per job. Pull requests from forks get read-only tokens by default. Always declare what you need:

permissions:
  contents: read          # default to the least
jobs:
  release:
    permissions:
      contents: write     # raise only where needed

Static keys vs OIDC

permissions:
  id-token: write
  contents: read
steps:
  - uses: aws-actions/configure-aws-credentials@<sha>
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-deploy
      aws-region: af-south-1

Equivalent login actions exist for Azure (azure/login) and Google Cloud (google-github-actions/auth). Cloud-side setup: 2. AWS IAM and Security, 5. Azure Identity and Security.

Matrix and Conditionals

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [20, 22]
    include:
      - os: ubuntu-latest
        node: 24
        experimental: true
    exclude:
      - os: windows-latest
        node: 20

• A matrix creates one job per combination; include and exclude fine-tune it
• fail-fast: false lets the other jobs finish when one fails; max-parallel caps concurrency

Dynamic matrix

Compute the matrix in a first job, then fan out:

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      services: ${{ steps.find.outputs.services }}
    steps:
      - uses: actions/checkout@<sha>
      - id: find
        run: echo "services=$(ls services | jq -R -s -c 'split("\n")[:-1]')" >> "$GITHUB_OUTPUT"
  test:
    needs: plan
    runs-on: ubuntu-latest
    strategy:
      matrix:
        service: ${{ fromJSON(needs.plan.outputs.services) }}
    steps:
      - run: echo "Testing ${{ matrix.service }}"

Useful in a monorepo: test only the services that changed.

Conditionals

- if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  run: ./deploy.sh
- if: failure()            # runs only when an earlier step failed
  run: ./notify.sh
- if: always()             # runs regardless
  run: ./cleanup.sh

Status functions: success() (default), failure(), always(), cancelled().

Workflow Commands

Specially formatted output lets a step talk to the runner:

The older ::set-output and ::set-env commands are deprecated; use the files above.

Marketplace Actions

Thousands of actions exist, so treat each as a third-party dependency:

1. Does it do exactly what you need, and nothing more?
2. Signals: verified publisher, stars, recent commits, open issues, a readable source
3. Read the code if it touches secrets or deploys
4. Pin to a full commit SHA, not a tag or branch:

# bad: moves under you
- uses: actions/checkout@v4
# good: immutable, with the version as a comment
- uses: actions/checkout@<full-40-character-commit-sha>   # v4.x.y

Tags can be re-pointed. In March 2025 a widely used action (tj-actions/changed-files, CVE-2025-30066) was compromised and leaked secrets from repositories that referenced it by tag, which is why SHA pinning matters. Automate the updates with Dependabot or Renovate.

Common Workflows

Pipeline concepts: 1. CI-CD Pipelines. Image build steps: 3. Container Images and Build Tools.

Best Practices

Performance

1. Measure first: baseline duration, queue time and cache hit rate
2. Wait less: enough runner capacity, fail fast with quick lint and type checks first
3. Do less: paths filters, if: conditions, caching, Docker layer caching (cache-from: type=gha)
4. Use resources well: parallel jobs and matrix, use every CPU core in tests, avoid emulation
5. Prevent regressions: alert on job-time creep, clean old caches and artifacts

Maintainability

• Give each repo a "CI API": a single task runner (Task, Make, Bazel) with standard commands (install, test, build, dev) so the workflow just calls task test and a developer can run the same thing locally
• Avoid copy-paste: composite actions and reusable workflows, versioned like libraries
• Iterate locally before pushing (Authoring and Testing GitHub Actions)
• Decide up front how logic is shared across a mono-repo or many repos

Security

• Least-privilege permissions:; prefer GITHUB_TOKEN to personal access tokens
• OIDC instead of stored cloud keys
• Pin actions by SHA
• No self-hosted runners for fork pull requests
• Environments with required reviewers for production deploys
• More: 5. Secure Coding and Supply Chain

Capstone Pattern

The course ends with a project that ties it together: pull request checks (lint, test), a build job that creates and pushes an image, and a deploy job gated by an environment, all calling shared tasks so the logic can be run locally with act. The repo layout and diagrams are in the capstone folder of the companion repo.