GitHub Actions — Complete Deep-Dive Engineering Guide

For a frontend engineer (React / Next.js / Astro / TypeScript) moving toward DevOps, CI/CD, automation, release engineering, and platform engineering.

Table of Contents

1. Big Picture

1.1 What GitHub Actions Are

GitHub Actions is an event-driven automation engine built directly into GitHub. It executes arbitrary code — your code, community-maintained actions, or shell scripts — in response to events that happen inside or around a repository.

You already know this pattern. When you run npm run dev, Vite watches files and re-renders on change. GitHub Actions does the same thing, but the “watcher” is GitHub itself, the “files” are Git events (pushes, PRs, tags, schedules, manual triggers), and the “render” is a pipeline of jobs that lint, test, build, deploy, notify, scan, release, or do anything a shell can do.

It is not just CI. It is a general-purpose workflow automation platform that happens to be excellent at CI/CD.

1.2 How GitHub Actions Differ From Things You Already Know

The React/Next.js analogy:

Think of your local npm run dev → npm run build → npm run start cycle. Now imagine GitHub automatically runs that cycle every time anyone on your team pushes code, but on a fresh clean machine, with results posted to the PR, and the build output deployed to a URL — all without you touching a terminal. That is GitHub Actions.

1.3 Core Concepts

Workflow

A YAML file in .github/workflows/ that defines an automation pipeline. One repository can have many workflows. Each workflow responds to one or more events.

Analogy: A workflow is like a next.config.js — it declares how the system should behave, and the platform interprets it.

Event

Something that triggers a workflow. Examples: push, pull_request, release, schedule, workflow_dispatch (manual button), workflow_call (called by another workflow).

Analogy: Events are like DOM events. A push is like an onClick — when it fires, registered handlers (workflows) run.

Job

A unit of work that runs on a single runner. Jobs within a workflow run in parallel by default, unless you declare dependencies with needs.

Analogy: Jobs are like independent React components — they render (execute) independently, but can pass data to each other.

Step

A single command or action within a job. Steps run sequentially, top to bottom.

Analogy: Steps are like lines inside a useEffect — they execute in order, sharing the same context (the runner’s filesystem and environment).

Runner

The machine (VM) that executes a job. GitHub provides hosted runners (Ubuntu, Windows, macOS) or you can use self-hosted runners.

Analogy: A runner is like a fresh npx create-next-app environment — clean, isolated, and disposable. Every job starts on a blank machine.

Action

A reusable, parameterized unit of workflow logic. Published to the GitHub Marketplace or defined locally. Called with uses:.

Analogy: An action is like an npm package for your pipeline — someone else wrote and tested it, you import it and pass props (inputs).

Matrix

A strategy that fans a single job definition into many parallel runs by varying parameters (Node versions, OS, config flags).

Analogy: Like rendering a component list with .map() — same template, different data per instance.

Artifact

A file or directory produced by a workflow run that you want to persist — build outputs, test reports, binaries. Uploaded with actions/upload-artifact, downloaded with actions/download-artifact.

Analogy: Like the out/ or dist/ directory from next build, but stored on GitHub for later jobs or manual download.

Cache

Stored dependency data (like node_modules or the pnpm store) that is restored on subsequent runs to skip expensive installs. Keyed by a hash of the lockfile.

Analogy: Like the .next/cache folder that makes rebuilds faster — but across CI runs.

Environment

A named deployment target (e.g., staging, production) with configurable protection rules — required reviewers, wait timers, branch restrictions, scoped secrets.

Analogy: Like Vercel’s “Preview” vs. “Production” distinction, but you define the rules yourself.

Secret

An encrypted value stored at the repository, environment, or organization level. Accessed via ${{ secrets.NAME }}. Masked in logs automatically.

Analogy: Like environment variables in Vercel or Cloudflare dashboards, but scoped to your pipeline.

1.4 The Lifecycle: git push → deployment

┌─────────────────────────────────────────────────────────────────────────┐
│ DEVELOPER                                                               │
│                                                                         │
│  git add . → git commit → git push origin main                         │
│                                                                         │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ GITHUB EVENT SYSTEM                                                     │
│                                                                         │
│  Event emitted: push (ref: refs/heads/main)                            │
│  GitHub scans .github/workflows/*.yml for matching triggers            │
│                                                                         │
└────────────────────────────┬────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ WORKFLOW EXECUTION                                                      │
│                                                                         │
│  ci.yml matched on: push.branches: [main]                              │
│                                                                         │
│  ┌──────────┐   ┌──────────┐                                           │
│  │ Job: lint │   │ Job: test │  ← parallel by default                  │
│  └─────┬────┘   └─────┬────┘                                           │
│        │               │                                                │
│        └───────┬───────┘                                                │
│                ▼                                                        │
│        ┌──────────────┐                                                 │
│        │  Job: build   │  ← needs: [lint, test]                        │
│        └──────┬───────┘                                                 │
│               ▼                                                        │
│        ┌──────────────┐                                                 │
│        │  Job: deploy  │  ← needs: build, environment: production      │
│        └──────────────┘                                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ DEPLOYMENT TARGET                                                       │
│                                                                         │
│  Vercel / Cloudflare Pages / AWS S3 / Docker registry / etc.           │
│  Status check reported back to GitHub                                  │
│  Deployment URL linked in PR or commit                                 │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

1.5 Comparison With Other CI/CD Systems

Key insight for a frontend engineer: Vercel gives you the best DX for deploying Next.js — zero config, instant previews, automatic production. GitHub Actions gives you the most control — you decide every step, can add security scanning, multi-platform testing, release gating, and deployment to any target. Most real teams use both: Vercel for deployment, Actions for everything else (lint, test, release, automation).

1.6 Mental Model Diagram

┌────────────────────────────────────────────────────┐
│                  YOUR REPOSITORY                    │
│                                                    │
│  src/  package.json  .github/workflows/ci.yml      │
│                                                    │
└────────────────────────┬───────────────────────────┘
                         │ git push / PR / tag / schedule / manual
                         ▼
┌────────────────────────────────────────────────────┐
│              GITHUB EVENT SYSTEM                    │
│                                                    │
│  Matches event → selects workflow(s)               │
│                                                    │
└────────────────────────┬───────────────────────────┘
                         │
           ┌─────────────┼─────────────┐
           ▼             ▼             ▼
      ┌─────────┐  ┌─────────┐  ┌─────────┐
      │ Job A   │  │ Job B   │  │ Job C   │   ← each on its own runner
      │ (lint)  │  │ (test)  │  │ (types) │
      └────┬────┘  └────┬────┘  └────┬────┘
           │             │             │
           └──────┬──────┘─────────────┘
                  ▼
            ┌───────────┐
            │  Job D    │   ← needs: [A, B, C]
            │  (build)  │
            └─────┬─────┘
                  │ upload artifact
                  ▼
            ┌───────────┐
            │  Job E    │   ← needs: D, environment: production
            │  (deploy) │
            └───────────┘
                  │
                  ▼
         Deploy to target

2. Learning Roadmap by Skill Level

Level 1 — Newbie

Goal: Create your first working workflow and understand every part of it.

What a workflow file is

A workflow file is a YAML document that lives in .github/workflows/. It tells GitHub: “When this event happens, run these jobs on these machines.”

You already manage config files — next.config.js, tsconfig.json, tailwind.config.ts. A workflow file is another config file, but for your automation pipeline instead of your app.

YAML basics you need

# Scalars (strings, numbers, booleans)
name: CI
timeout-minutes: 10

# Mappings (key-value pairs — like JS objects)
env:
  NODE_ENV: production
  CI: true

# Sequences (lists — like JS arrays)
branches:
  - main
  - develop

# Multi-line strings
run: |
  echo "Line 1"
  echo "Line 2"

# Inline flow syntax
branches: [main, develop]

Critical YAML rules:

• Indentation is spaces only — never tabs.
• Indentation level defines structure (like Python).
• Colons need a space after them: key: value not key:value.
• The values true, false, on, off, yes, no are booleans in YAML — quote them if you mean strings.

Where workflows live

your-repo/
└── .github/
    └── workflows/
        ├── ci.yml          ← runs on push and PR
        ├── deploy.yml      ← runs on merge to main
        └── nightly.yml     ← runs on schedule

GitHub only reads workflow files from .github/workflows/. The filenames can be anything ending in .yml or .yaml.

First workflow — the complete “Hello World”

# .github/workflows/hello.yml
name: Hello World

on:
  push:
    branches: [main]

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Say hello
        run: echo "Hello from GitHub Actions!"

      - name: Show environment
        run: |
          echo "Runner OS: ${{ runner.os }}"
          echo "Event: ${{ github.event_name }}"
          echo "Branch: ${{ github.ref }}"
          echo "SHA: ${{ github.sha }}"

First real workflow — lint + test + build

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

      - name: Build
        run: npm run build

Why npm ci instead of npm install?

npm ci does a clean install from the lockfile — faster, deterministic, and will fail if package-lock.json is out of sync. This is what you always want in CI. npm install can modify the lockfile, introducing drift.

How to debug failures

1. Read the failing step’s logs. Click the red X → click the failing job → expand the failing step. The error message is usually right there.
2. Check the YAML syntax. GitHub shows a parse error banner if your YAML is malformed. Use a local YAML linter or VS Code’s YAML extension.
3. Reproduce locally. Run the exact same commands on your machine. If it works locally but fails in CI, the difference is usually: Node version, missing dependency, environment variable, or file path.
4. Add debug output.

   - name: Debug info
     run: |
       node --version
       npm --version
       ls -la
       cat package.json
       echo "Event: ${{ toJSON(github.event) }}"

5. Enable debug logging. Re-run the workflow with “Enable debug logging” checked, or set the repository secret ACTIONS_STEP_DEBUG to true.
6. Check the event payload. Use ${{ toJSON(github.event) }} to see exactly what data GitHub sent.

Common mistakes at this level

5 small practice exercises

1. Print your toolchain: Create a workflow that prints the Node.js version, npm version, and Git version on every push.
2. Lint on PR: Create a workflow that runs npm run lint only on pull requests.
3. Multi-step build: Create a workflow with separate steps for install, lint, test, and build.
4. Break it intentionally: Introduce a lint error, push it, and study the failure logs. Then fix it.
5. Branch filtering: Create a workflow that runs on pushes to main and develop but not other branches.

Level 1 success criteria

• Can create a .github/workflows/ci.yml from scratch.
• Can explain trigger, job, step, runner, and action.
• Can read failure logs and fix basic errors.
• Can explain why npm ci is used instead of npm install.

Level 2 — Junior

Goal: Build workflows a team actually uses — multi-job, cached, conditional, with deployments.

Multiple jobs and dependencies

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run typecheck

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test -- --ci

  build:
    runs-on: ubuntu-latest
    needs: [lint, typecheck, test] # ← waits for all three
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
          retention-days: 7

Why separate jobs? Faster feedback. If lint fails in 20 seconds, you know immediately — even if tests take 5 minutes. Each job runs on its own runner in parallel unless constrained by needs.

Trade-off: Each job does a fresh checkout and install. This costs time. Caching mitigates it. For very small projects, a single job may be faster end-to-end.

Matrix builds

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false # ← don't cancel others if one fails
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [18, 20, 22]
        exclude:
          - os: macos-latest
            node-version: 18 # ← skip this combination
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test

When to use a matrix: When you genuinely need cross-platform or cross-version confidence. For most frontend apps, a single OS and Node version is enough. Save matrices for libraries, packages, and tools.

Caching — npm, pnpm, and yarn

The actions/setup-node action has built-in caching:

# npm
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm # ← caches based on package-lock.json hash

# pnpm
- uses: pnpm/action-setup@v4
  with:
    version: 9
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: pnpm # ← caches based on pnpm-lock.yaml hash

# yarn
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: yarn # ← caches based on yarn.lock hash

What gets cached? Not node_modules itself — the package manager’s global cache directory. On cache hit, npm ci / pnpm install still runs but reads from local cache instead of the network.

Advanced: manual caching with actions/cache:

- uses: actions/cache@v4
  with:
    path: |
      ~/.npm
      .next/cache
    key: ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
    restore-keys: |
      ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}-
      ${{ runner.os }}-nextjs-

Environment variables and secrets

# Workflow-level env
env:
  CI: true
  NODE_ENV: production

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_TARGET: staging # ← job-level env
    steps:
      - name: Deploy
        env:
          API_TOKEN: ${{ secrets.API_TOKEN }} # ← step-level, from secrets
          DEPLOY_URL: ${{ vars.DEPLOY_URL }} # ← from repository variables
        run: |
          echo "Deploying to $DEPLOY_TARGET"
          ./deploy.sh

Secret rules:

• Secrets are encrypted at rest and masked in logs.
• They cannot be read back from the UI after creation.
• Use environment-scoped secrets for production credentials.
• Never echo secrets directly — GitHub masks them, but be careful with encoded/transformed values.

Conditional execution

# Run only on main branch
- name: Deploy
  if: github.ref == 'refs/heads/main'
  run: npm run deploy

# Run only on PRs
- name: Preview
  if: github.event_name == 'pull_request'
  run: npm run build:preview

# Run only when a specific label is present
- name: Full test
  if: contains(github.event.pull_request.labels.*.name, 'full-test')
  run: npm run test:e2e

# Run even if a previous step failed
- name: Cleanup
  if: always()
  run: ./cleanup.sh

# Run only if previous steps succeeded (default behavior)
- name: Deploy
  if: success()
  run: npm run deploy

# Run only if a previous step failed
- name: Notify failure
  if: failure()
  run: curl -X POST $SLACK_WEBHOOK -d '{"text":"CI failed!"}'

Pull request workflows

PR workflows are your primary quality gate:

name: PR Checks

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --ci
      - run: npm run build

  # Post build size as a PR comment
  bundle-size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: andresz1/size-limit-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}

Deployment basics

deploy:
  runs-on: ubuntu-latest
  needs: build
  if: github.ref == 'refs/heads/main'
  environment:
    name: production
    url: https://myapp.com
  steps:
    - uses: actions/download-artifact@v4
      with:
        name: build-output
    - name: Deploy to hosting
      env:
        DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
      run: |
        npx wrangler pages deploy dist/ --project-name=my-site

5 mini project ideas

1. React CI with bundle size tracking: Lint, test, build, and post bundle size diff as a PR comment.
2. Next.js preview deployment: On PR, build and deploy a preview to Vercel or Cloudflare Pages.
3. Astro static site deployment: Build and deploy Astro output to GitHub Pages on merge to main.
4. Matrix test across Node versions: Test a shared utility library across Node 18, 20, and 22.
5. Automated dependency updates: Configure Dependabot + auto-merge for patch updates that pass CI.

Common mistakes and anti-patterns

Level 2 success criteria

• Can structure multi-job workflows with needs.
• Can explain and configure caching.
• Can use matrix builds purposefully.
• Can use secrets and environment variables correctly.
• Can build a basic deploy pipeline with conditions.

Level 3 — Senior

Goal: Build production-ready CI/CD — fast, secure, maintainable, with deployment safety.

Branch strategy integration

Map workflows to your Git strategy:

Feature branch  → PR workflow: lint, test, typecheck, build, preview deploy
Main branch     → CI + deploy to staging (automatic)
Release tag     → Deploy to production (with approval)
Hotfix branch   → Fast-track CI + deploy to production

on:
  pull_request: # ← feature branches
  push:
    branches: [main] # ← staging deploy trigger
    tags: ['v*'] # ← production deploy trigger

Monorepo workflows with path filters

name: Frontend CI

on:
  push:
    paths:
      - 'packages/web/**'
      - 'packages/shared/**'
      - 'package.json'
      - 'pnpm-lock.yaml'
  pull_request:
    paths:
      - 'packages/web/**'
      - 'packages/shared/**'

jobs:
  web-ci:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: packages/web
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run lint
      - run: pnpm run test
      - run: pnpm run build

Advanced change detection: For complex monorepos, path filters are too coarse. Use a change detection step:

- uses: dorny/paths-filter@v3
  id: changes
  with:
    filters: |
      web:
        - 'packages/web/**'
        - 'packages/shared/**'
      api:
        - 'packages/api/**'
        - 'packages/shared/**'

- name: Run web tests
  if: steps.changes.outputs.web == 'true'
  run: pnpm --filter web test

Reusable workflows

Define once, call from many repos:

# .github/workflows/reusable-ci.yml (in a shared repo)
name: Reusable CI

on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
      working-directory:
        type: string
        default: '.'
      package-manager:
        type: string
        default: 'npm'
    secrets:
      deploy-token:
        required: false

jobs:
  ci:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: ${{ inputs.package-manager }}
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

# .github/workflows/ci.yml (in a consuming repo)
name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    uses: my-org/shared-workflows/.github/workflows/reusable-ci.yml@main
    with:
      node-version: '20'
      package-manager: npm
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}

Composite actions

Reusable step-level logic (not full jobs):

# .github/actions/setup-project/action.yml
name: Setup Project
description: Checkout, install Node, install dependencies

inputs:
  node-version:
    description: Node.js version
    default: '20'

runs:
  using: composite
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash

# Usage in a workflow
steps:
  - uses: ./.github/actions/setup-project
    with:
      node-version: '20'
  - run: npm run lint
  - run: npm test

Reusable workflow vs composite action — decision table

Self-hosted runners

Use them when you need:

• Private network access (VPN, internal APIs)
• Heavy compute (large Docker builds, ML jobs)
• Specialized hardware (GPU, ARM)
• Large artifact handling
• Cost control at scale

Runner management rules:

• Use ephemeral runners when possible (fresh VM per job).
• Never store long-lived secrets on runner machines.
• Patch and update regularly.
• Isolate by trust boundary — don’t share runners between public and private repos.
• Monitor runner health and queue depth.

Secure secret management

OIDC example — deploying to AWS without static keys:

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/github-actions
      aws-region: us-east-1
  - run: aws s3 sync dist/ s3://my-bucket/

Deployment strategies

Release automation

name: Release

on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true
          files: dist/**

Semantic release automation:

- uses: cycjimmy/semantic-release-action@v4
  with:
    branches: |
      ['main']
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Rollback strategy

Rule: Define rollback before you define deploy. If you cannot answer “how do I undo this?”, you are not ready to ship.

Approaches:

1. Re-deploy previous artifact: Keep artifacts with retention-days. On failure, re-run the deploy job pointing at the last good artifact.
2. Git revert + re-deploy: Create a revert commit, push, and let the pipeline deploy the reverted code.
3. Traffic switch: With blue-green or canary, route traffic back to the old version instantly.
4. Feature flag disable: If the new code is behind a flag, turn it off.

# Manual rollback workflow
name: Rollback

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to (e.g., v1.2.3)'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.version }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm run deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

CI optimization

Notifications and incident handling

# Slack notification on failure
- name: Notify Slack
  if: failure()
  uses: slackapi/slack-github-action@v2
  with:
    webhook: ${{ secrets.SLACK_WEBHOOK }}
    webhook-type: incoming-webhook
    payload: |
      {
        "text": "❌ CI failed on ${{ github.ref }} — ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
      }

5 production-grade project examples

1. Next.js monorepo CI/CD: Path-filtered CI, parallel lint/test/build, artifact-based deploy to Vercel with preview environments for PRs and production deployment on tag.
2. Astro static site with Cloudflare Pages: Build on PR for preview, deploy to production on main, with cache warming and bundle size tracking.
3. Automated release pipeline: Semantic versioning from commit messages, auto-generated changelog, GitHub Release creation, and deployment trigger.
4. Docker image build and publish: Multi-platform Docker build with caching, vulnerability scanning, image signing, and push to GHCR (GitHub Container Registry).
5. Organization-wide shared CI: Reusable workflows for lint/test/build/deploy consumed by 20+ repos, with centralized updates and version pinning.

Level 3 success criteria

• Can design a maintainable multi-job pipeline for a real team.
• Can implement reusable workflows and composite actions.
• Can reduce CI cost and duration measurably.
• Can explain deployment safety, rollback, and environment protection.
• Can secure secrets with OIDC and environment scoping.

Level 4 — Expert

Goal: Design and operate a CI/CD platform at organization scale.

At this level you are not writing one workflow — you are designing the system that all workflows run inside. You think about governance, cost, reliability, security, and developer experience across hundreds of repositories.

Building an internal CI/CD platform

Your platform provides:

• Standardized reusable workflows for every language and framework.
• Opinionated defaults (Node version, package manager, test framework, deploy target).
• Escape hatches for teams that need customization.
• Observability — dashboards for CI cost, duration, flakiness, and failure rates.
• Guardrails — policies that prevent insecure or wasteful patterns.

Organization-wide reusable workflows

Structure:

my-org/ci-workflows/
├── .github/workflows/
│   ├── frontend-ci.yml          ← called by all frontend repos
│   ├── backend-ci.yml           ← called by all backend repos
│   ├── docker-build.yml         ← called by all containerized services
│   ├── deploy-preview.yml       ← shared preview deploy logic
│   ├── deploy-production.yml    ← shared production deploy with approval
│   ├── release.yml              ← shared release automation
│   └── security-scan.yml        ← shared security scanning
└── README.md

Versioning strategy: Use tagged releases of the shared workflow repo. Consuming repos pin to a version:

uses: my-org/ci-workflows/.github/workflows/frontend-ci.yml@v2.1.0

This prevents breaking changes from propagating instantly.

Governance and policy enforcement

Multi-repository automation

Use workflow_dispatch with API calls to trigger workflows across repos:

# Trigger a deploy in another repo
- name: Trigger deploy
  uses: peter-evans/repository-dispatch@v3
  with:
    token: ${{ secrets.CROSS_REPO_TOKEN }}
    repository: my-org/production-deploy
    event-type: deploy-frontend
    client-payload: '{"version": "${{ github.sha }}", "repo": "${{ github.repository }}"}'

Multi-environment promotion pipeline

PR → preview (automatic)
     ↓ merge
main → staging (automatic)
     ↓ manual approval
staging → production (protected environment)
     ↓ monitor
production → rollback (manual dispatch)

deploy-staging:
  needs: build
  if: github.ref == 'refs/heads/main'
  environment:
    name: staging
    url: https://staging.myapp.com
  # ...

deploy-production:
  needs: deploy-staging
  environment:
    name: production
    url: https://myapp.com
  # ← requires manual approval via environment protection rules
  # ...

Advanced self-hosted runner architecture

┌─────────────────────────────────────────────────┐
│ RUNNER FLEET                                     │
│                                                 │
│  Pool: general-purpose (auto-scaled)            │
│    ├── ubuntu-latest × N (ephemeral)            │
│    └── scale-to-zero when idle                  │
│                                                 │
│  Pool: docker-builds (large instances)          │
│    ├── 8 CPU / 32 GB RAM                        │
│    └── Docker layer cache on persistent volume  │
│                                                 │
│  Pool: trusted (for production deploys)         │
│    ├── Network access to production             │
│    ├── Strict access controls                   │
│    └── Separate from CI pool                    │
│                                                 │
└─────────────────────────────────────────────────┘

Key architectural decisions:

• Ephemeral runners for isolation (no state between jobs).
• Separate pools by trust boundary.
• Autoscale based on queue depth.
• Use actions/runner-controller (ARC) for Kubernetes-based scaling.
• Monitor runner utilization and queue wait times.

Security hardening

Action pinning — SHA vs. tag:

# Tag — convenient, but mutable:
uses: actions/checkout@v4

# SHA — immutable, auditable:
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

For critical production workflows, SHA pinning with Dependabot updates is the gold standard.

Supply chain security

• Use actions/attest-build-provenance for artifact attestation.
• Sign container images with cosign.
• Scan dependencies with github/codeql-action and ossf/scorecard-action.
• Generate SBOMs (Software Bill of Materials) for releases.
• Enforce lockfile integrity — fail CI if lockfile is missing or outdated.

OIDC and cloud credentials

Problem: Static cloud access keys (AWS, GCP, Azure) stored as secrets are long-lived and risky.

Solution: OIDC (OpenID Connect) federated identity — GitHub mints a short-lived JWT, your cloud provider exchanges it for temporary credentials.

permissions:
  id-token: write
  contents: read

steps:
  # AWS
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/deploy
      aws-region: us-east-1

  # GCP
  - uses: google-github-actions/auth@v2
    with:
      workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
      service_account: deploy@my-project.iam.gserviceaccount.com

  # Azure
  - uses: azure/login@v2
    with:
      client-id: ${{ secrets.AZURE_CLIENT_ID }}
      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

Disaster recovery for CI/CD systems

Architecture review checklist

Use this when reviewing any production workflow:

• Is the pipeline idempotent? (Re-running produces the same result)
• Are secrets minimized and scoped?
• Are jobs parallelized where useful?
• Can we rollback safely?
• Are workflows reusable and DRY?
• Are logs and artifacts sufficient for incident response?
• Are runner permissions appropriate?
• Are external actions trusted and pinned?
• Is the pipeline cost-efficient?
• Are environments protected appropriately?
• Is there a documented failure recovery path?
• Are notifications configured for failures?

What expert engineers care about that juniors miss

10 advanced engineering discussion topics

1. Runner economics: At what scale do self-hosted runners become cheaper than GitHub-hosted? Include maintenance, networking, security, and ops cost.
2. Workflow as product: Should the platform team treat reusable workflows as internal products with SLOs, changelogs, and migration guides?
3. Multi-tenancy: How do you isolate CI for different teams in a single GitHub organization while sharing common infrastructure?
4. Pipeline observability: What metrics should you track? Propose a dashboard for CI health across 100+ repos.
5. Action supply chain: Design a policy for evaluating, approving, and monitoring third-party actions.
6. Migration strategy: How would you migrate 50 repos from Jenkins to GitHub Actions without disrupting teams?
7. Secrets at scale: Design a secrets management architecture for an org with 200 repos, 10 environments, and 5 cloud providers.
8. Monorepo CI scaling: At 500 packages, path filters break down. What architectural patterns handle this?
9. Incident response: A compromised action was used in production workflows. Design the response playbook.
10. Cost allocation: How do you attribute CI costs to teams, projects, or products for budget planning?

3. Setup Guide

Step 1: Create the workflows directory

mkdir -p .github/workflows

Step 2: Use clear naming conventions

Convention: Name files by intent (what they do), not by implementation (how they do it).

Step 3: Basic workflow structure

Every workflow has three parts:

# 1. NAME — human-readable label
name: CI

# 2. TRIGGERS — when does this run?
on:
  push:
    branches: [main]
  pull_request:

# 3. JOBS — what does this do?
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello"

Step 4: Complete example workflows

Lint workflow

name: Lint

on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint

Test workflow

name: Test

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test -- --ci --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-report
          path: coverage/

Build workflow

name: Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/
          retention-days: 14

Deploy workflow

name: Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/
      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: echo "Deploy dist/ to production"

Step 5: Framework-specific examples

React app with Vite

name: React CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: react-build
          path: dist/

Next.js app

name: Next.js CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - uses: actions/cache@v4
        with:
          path: .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('package-lock.json') }}-
            ${{ runner.os }}-nextjs-
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test
      - run: npm run build

  deploy-preview:
    needs: ci
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy preview to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

  deploy-production:
    needs: ci
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Vercel (production)
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

Astro static site

name: Astro CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: astro-site
          path: dist/

  deploy:
    needs: ci
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: production
    permissions:
      pages: write
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: astro-site
          path: dist/
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist/
      - uses: actions/deploy-pages@v4

pnpm setup (shared pattern)

steps:
  - uses: actions/checkout@v4
  - uses: pnpm/action-setup@v4
    with:
      version: 9
  - uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: pnpm
  - run: pnpm install --frozen-lockfile

yarn setup (shared pattern)

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 20
      cache: yarn
  - run: yarn install --frozen-lockfile

Step 6: Caching strategy

Cache key design:

key: ${{ runner.os }}-${{ inputs.package-manager }}-${{ hashFiles('**/lockfile') }}
restore-keys: |
  ${{ runner.os }}-${{ inputs.package-manager }}-

The restore-keys enable partial cache hits — better than no cache, even if not exact.

Step 7: Secret setup

1. Go to Settings → Secrets and variables → Actions in your repository.
2. Add repository secrets for project-specific values.
3. Create environments (staging, production) and add environment-specific secrets there.
4. For organization-wide secrets, use organization-level settings.

Common secrets:

Step 8: Environment setup

1. Go to Settings → Environments.
2. Create environments: preview, staging, production.
3. Configure protection rules for production:
   • Required reviewers (at least 1-2 people)
   • Wait timer (optional — e.g., 5 minutes)
   • Restrict to specific branches (only main or release/*)
4. Add environment-specific secrets and variables.

Step 9: Branch protection integration

1. Go to Settings → Branches → Branch protection rules.
2. Add a rule for main:
   • Require a pull request before merging
   • Require status checks to pass (select your CI job names)
   • Require branches to be up to date
   • Require review from code owners (optional)
3. Your CI workflow job names become the required status checks.

Example repository structure

my-project/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                 ← lint, typecheck, test, build
│   │   ├── deploy-preview.yml     ← preview on PR
│   │   ├── deploy-production.yml  ← deploy on merge to main
│   │   ├── release.yml            ← tag-based release
│   │   └── nightly.yml            ← scheduled checks
│   ├── actions/
│   │   └── setup-project/
│   │       └── action.yml         ← composite action for shared setup
│   ├── CODEOWNERS                 ← protect .github/ changes
│   └── dependabot.yml             ← automated dependency updates
├── src/
├── tests/
├── public/
├── package.json
├── package-lock.json              ← or pnpm-lock.yaml
├── tsconfig.json
└── README.md

4. Cheatsheet

Workflow syntax quick reference

name: string                          # Human-readable name
on: event | [events] | {event: config}  # Triggers
permissions: {scope: level}           # Token permissions
env: {KEY: value}                     # Workflow-level env vars
concurrency:                          # Prevent duplicate runs
  group: string
  cancel-in-progress: boolean
jobs:
  job-id:
    runs-on: runner-label
    needs: [job-ids]                  # Dependencies
    if: expression                    # Condition
    environment: name | {name, url}   # Deployment target
    timeout-minutes: number           # Job timeout
    strategy:
      matrix: {key: [values]}
      fail-fast: boolean
    defaults:
      run:
        working-directory: path
    steps:
      - name: string                  # Step label
        uses: owner/action@ref        # Use an action
        with: {input: value}          # Action inputs
        run: command                   # Shell command
        env: {KEY: value}             # Step-level env vars
        if: expression                # Step condition
        id: step-id                   # Reference this step
        working-directory: path
        shell: bash | pwsh | python
        continue-on-error: boolean

Triggers (events)

Expressions

# Context variables
${{ github.ref }}                          # refs/heads/main
${{ github.sha }}                          # full commit SHA
${{ github.event_name }}                   # push, pull_request, etc.
${{ github.actor }}                        # who triggered
${{ github.repository }}                   # owner/repo
${{ github.run_id }}                       # unique run ID
${{ github.run_number }}                   # incrementing run number
${{ runner.os }}                           # Linux, Windows, macOS
${{ matrix.node-version }}                 # current matrix value
${{ secrets.MY_SECRET }}                   # secret value
${{ vars.MY_VAR }}                         # repository/org variable
${{ steps.step-id.outputs.key }}           # step output
${{ needs.job-id.outputs.key }}            # job output
${{ env.MY_VAR }}                          # environment variable

# Functions
${{ hashFiles('**/package-lock.json') }}   # file hash for cache keys
${{ toJSON(github.event) }}                # JSON dump for debugging
${{ contains(github.ref, 'release') }}     # string contains
${{ startsWith(github.ref, 'refs/tags') }} # string starts with
${{ format('Hello {0}', github.actor) }}   # string format
${{ fromJSON(steps.id.outputs.json) }}     # parse JSON

Conditions

# Branch conditions
if: github.ref == 'refs/heads/main'
if: github.ref != 'refs/heads/main'
if: startsWith(github.ref, 'refs/tags/v')

# Event conditions
if: github.event_name == 'pull_request'
if: github.event_name == 'push'
if: github.event_name == 'workflow_dispatch'

# Label conditions
if: contains(github.event.pull_request.labels.*.name, 'deploy')

# Status conditions
if: success()          # all previous steps succeeded (default)
if: failure()          # any previous step failed
if: always()           # run regardless
if: cancelled()        # run was cancelled

# Combining conditions
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
if: github.event_name == 'pull_request' || github.event_name == 'push'

Matrix patterns

# Basic matrix
strategy:
  matrix:
    node: [18, 20, 22]

# Multi-dimensional
strategy:
  matrix:
    node: [18, 20]
    os: [ubuntu-latest, macos-latest]

# With exclusions
strategy:
  matrix:
    node: [18, 20]
    os: [ubuntu-latest, macos-latest]
    exclude:
      - node: 18
        os: macos-latest

# With inclusions (add specific combos)
strategy:
  matrix:
    node: [18, 20]
    include:
      - node: 22
        os: ubuntu-latest
        experimental: true

# Don't cancel others on failure
strategy:
  fail-fast: false
  matrix:
    node: [18, 20, 22]

Cache patterns

# Built-in (simplest)
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: npm # or pnpm, yarn

# Manual cache
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
    restore-keys: ${{ runner.os }}-npm-

# Next.js build cache
- uses: actions/cache@v4
  with:
    path: .next/cache
    key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('src/**') }}
    restore-keys: |
      nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
      nextjs-${{ runner.os }}-

Artifact patterns

# Upload
- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: dist/
    retention-days: 7
    if-no-files-found: error # fail if nothing to upload

# Download (in a later job)
- uses: actions/download-artifact@v4
  with:
    name: build-output
    path: dist/

# Upload multiple
- uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: |
      coverage/
      test-results/

Concurrency control

# Cancel previous runs on same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Don't cancel production deploys
concurrency:
  group: deploy-production
  cancel-in-progress: false

Job outputs

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      should-deploy: ${{ steps.check.outputs.deploy }}
    steps:
      - id: check
        run: echo "deploy=true" >> "$GITHUB_OUTPUT"

  deploy:
    needs: detect
    if: needs.detect.outputs.should-deploy == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying..."

Common marketplace actions

Debugging tips

Common errors and fixes

YAML pitfalls

Performance optimization

Security best practices

5. Real-World Engineering Mindset

CI for React / Next.js / Astro

Problem: Every PR needs fast, reliable feedback on code quality and correctness.

Strategies:

By team size:

• Small (1–3): Single job is fine. Simplicity wins.
• Medium (4–15): Parallel jobs with caching. Speed matters now.
• Large (15+): Reusable workflows, shared composite actions, path filters.

Hidden pitfalls:

• Tests that pass locally but fail in CI due to timezone, locale, or font issues.
• Flaky tests eroding team trust in CI.
• Build cache invalidation causing stale behavior.

Cost: Free tier gives 2,000 minutes/month for private repos. A 4-job pipeline running 3 minutes each, 20 times/day = 240 minutes/day = 7,200 minutes/month → you will exceed free tier quickly. Cache everything.

Senior choice: Parallel jobs (lint, typecheck, test), cached installs, build only after all pass. Add concurrency cancellation to avoid wasting minutes on superseded pushes.

Deploying static sites

Problem: Ship built HTML/CSS/JS to a CDN reliably.

Strategies:

Senior choice: For simple static sites (Astro, Vite), Cloudflare Pages or GitHub Pages. For Next.js with server-side features, Vercel. For maximum control, S3 + CloudFront with OIDC auth.

Deploying to Vercel

Problem: You want preview deployments on PRs and production deploys on merge.

Strategies:

Hidden pitfalls:

• Vercel auto-deploys on push. If you also deploy from Actions, you get double deployments.
• To use Actions-only, disable Vercel’s GitHub integration and use the CLI.

Senior choice: Hybrid. Let Vercel handle deployment (its DX is superior), use Actions for lint/test/typecheck/security. This is the most common pattern in production Next.js teams.

Deploying to Cloudflare Pages / Workers

Problem: Publish edge content or Worker code with consistent validation.

Strategies:

# Deploy Astro to Cloudflare Pages
- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    projectName: my-site
    directory: dist/

Senior choice: For static sites, Cloudflare’s native integration is excellent. For Workers with complex build steps, use Actions + Wrangler.

Docker build and deployment

Problem: Build container images reproducibly, scan them, and push to a registry.

name: Docker Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    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:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Strategies:

Senior choice: GitHub-hosted runner with docker/build-push-action and cache-from: type=gha for most teams. Move to self-hosted when build times exceed 10 minutes.

Preview deployments

Problem: Reviewers want to see and interact with changes before merge.

Strategies:

Senior choice: Use platform-native previews (Vercel, Cloudflare). For full-stack apps, spin up ephemeral environments only for critical PRs.

Monorepo selective builds

Problem: Running all CI for all packages on every change is wasteful.

Strategies:

# Using dorny/paths-filter
- uses: dorny/paths-filter@v3
  id: filter
  with:
    filters: |
      web:
        - 'apps/web/**'
        - 'packages/ui/**'
        - 'packages/utils/**'
      api:
        - 'apps/api/**'
        - 'packages/db/**'

- name: Web CI
  if: steps.filter.outputs.web == 'true'
  run: pnpm --filter web test && pnpm --filter web build

Senior choice: Change detection + Turborepo for large monorepos. Simple path filters for small ones.

Versioning and release automation

Problem: Releases need consistency, traceability, and should not depend on human memory.

Strategies:

# Using Google's release-please
name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: googleapis/release-please-action@v4
        with:
          release-type: node

Senior choice: release-please for apps (structured, auditable). semantic-release for libraries (fully automated). Both require commit message discipline.

Running database migrations

Problem: If deploy succeeds but migration fails, the app may be broken.

Strategies:

Senior choice: Expand/contract migrations. Make schema changes backward-compatible so old and new code can coexist. Deploy code first, then apply schema changes. This is the only safe approach for zero-downtime systems.

Dependabot automation

Problem: Dependabot creates many PRs that need review.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    groups:
      minor-and-patch:
        update-types: [minor, patch]
    open-pull-requests-limit: 10

# .github/workflows/dependabot-merge.yml
name: Dependabot Auto-merge

on:
  pull_request:

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-merge:
    if: github.actor == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: dependabot/fetch-metadata@v2
        id: metadata
      - if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
        run: gh pr merge "${{ github.event.pull_request.number }}" --auto --squash
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Senior choice: Group minor/patch updates, auto-merge patches that pass CI, manually review major updates.

Security scanning

name: Security

on:
  pull_request:
  schedule:
    - cron: '0 6 * * 1' # weekly Monday 6 AM

jobs:
  codeql:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript-typescript
      - uses: github/codeql-action/analyze@v3

  dependency-review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/dependency-review-action@v4

Senior choice: Run CodeQL on PRs and weekly. Add dependency review on PRs. Use OSSF Scorecard for supply chain assessment.

Auto-labeling PRs

# .github/labeler.yml
frontend:
  - changed-files:
      - any-glob-to-any-file: ['src/components/**', 'src/pages/**']

docs:
  - changed-files:
      - any-glob-to-any-file: ['docs/**', '*.md']

ci:
  - changed-files:
      - any-glob-to-any-file: ['.github/**']

name: Label PR

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  label:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/labeler@v5

Generating changelogs

Strategies:

Senior choice: Conventional commits + automated generation for mature teams. GitHub auto-generated release notes for small teams.

Multi-environment deployment

name: Deploy

on:
  push:
    branches: [main]
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build
          path: dist/

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.myapp.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build
          path: dist/
      - run: echo "Deploy to staging"

  deploy-production:
    needs: deploy-staging
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://myapp.com
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: build
          path: dist/
      - run: echo "Deploy to production"

Senior choice: Reusable deploy workflow called with different environment inputs. Build once, deploy many times.

Rollback after failed deployment

Problem: Production is broken after a deploy. How fast can you recover?

Strategies:

# Manual rollback trigger
name: Rollback Production

on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Git tag or SHA to rollback to'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.version }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: echo "Rolling back to ${{ github.event.inputs.version }}"

Senior choice: Make rollback a first-class workflow with manual dispatch. Test it regularly. Know your RTO (Recovery Time Objective).

Scheduled workflows

name: Nightly

on:
  schedule:
    - cron: '0 2 * * *' # 2 AM UTC daily

jobs:
  nightly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run test:e2e
      - run: npm audit
      - name: Notify on failure
        if: failure()
        run: |
          curl -X POST "${{ secrets.SLACK_WEBHOOK }}" \
            -H 'Content-type: application/json' \
            -d '{"text":"🌙 Nightly build failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}'

Cron syntax quick reference:

Pitfall: Scheduled workflows only run on the default branch. If your workflow is on a feature branch, it won’t trigger on schedule.

Nightly builds

Problem: PR-time CI might not catch issues that appear only with full test suites, integration tests, or across platforms.

Strategies:

Senior choice: Run the broadest matrix nightly. Run the focused matrix on PRs. Alert the team on Slack/email if the nightly fails.

6. Brainstorm / Open Questions

Architecture

1. What should be standardized in shared workflows vs. left to each repo?
2. When should a workflow be split into multiple workflows?
3. When should a workflow become a reusable workflow?
4. When should a reusable workflow become a platform service?
5. What does the ideal pipeline DAG (directed acyclic graph) look like for your organization?
6. Which parts of CI should be event-driven and which should be scheduled?
7. How much conditional logic is acceptable before a workflow becomes unmaintainable?
8. Should workflows define their own Node version, or should that be centralized?

Scaling

9. What happens if this workflow takes 30 minutes instead of 3?
10. How many parallel jobs can your runner fleet actually support at peak?
11. What workflows become too expensive to run on every PR?
12. How do you handle bursts when 20 teams push simultaneously?
13. How do you detect and reduce redundant workflow executions?
14. What is the right level of workflow reuse across 50 repos? 500 repos?
15. How do you prevent duplicated YAML logic across repositories?
16. At what point should you invest in self-hosted runners?

Security

17. How do you avoid leaking secrets in logs — even transformed or base64-encoded ones?
18. Which jobs should never have access to production secrets?
19. Should third-party actions be pinned to commit SHAs or version tags?
20. Where should OIDC replace static cloud credentials?
21. How do you review workflow file changes with the same rigor as application code?
22. What should happen if a workflow file is compromised via a supply chain attack?
23. How do you segment trusted and untrusted runners?
24. What is your process for vetting a new action from the marketplace?
25. How do you detect if a previously-trusted action changes behavior silently?

DX / Maintainability

26. Can a new engineer understand the pipeline in under 10 minutes?
27. Which steps are noisy or flaky enough to degrade trust in CI?
28. Where is caching helpful vs. where does it cause confusion?
29. How do you surface the real failure instead of a cascade of follow-on errors?
30. What should be reusable, and what should remain explicit for readability?
31. How do you keep YAML complexity from becoming tribal knowledge?
32. What is the best default workflow template for your team?
33. How do you test workflow changes safely before merging?

Cost

34. Which jobs cost the most minutes without proportional value?
35. Can you skip the entire pipeline for docs-only or README changes?
36. Should you run full matrix tests on every commit, or only on specific triggers?
37. How much does artifact retention cost over time?
38. Are self-hosted runners actually cheaper after including maintenance and ops?
39. Are your caches helping enough to justify their complexity?
40. What is the cost of a slow pipeline in developer time and context switching?

Reliability

41. What should happen if deployment succeeds but the database migration fails?
42. How do you design for re-runs after flaky infrastructure outages?
43. How do you ensure artifacts are reproducible and traceable?
44. What should be automatically retried vs. manually investigated?
45. How do you detect partial failures that look successful at first glance?
46. What is your rollback RTO (Recovery Time Objective)?
47. How do you keep scheduled workflows trustworthy over months?

Release Strategy

48. When should you release on merge vs. on tag?
49. Should production deployment be gated by manual approval?
50. How should preview deployments map to release confidence?
51. What release process works best for a monorepo with multiple products?
52. When should database migrations be decoupled from app deployment?
53. What does a safe canary look like for your technology stack?
54. How do you reconcile fast shipping with controlled, safe releases?
55. What is the right balance between release automation and human judgment?

7. Practice Questions

Beginner (Level 1)

Q1. Multiple choice: Where do GitHub Actions workflow files live?

• A. src/workflows/
• B. .github/workflows/
• C. .vscode/tasks/
• D. actions/

Q2. True/False: A job runs on a runner.

Q3. Fill in the blank: The command npm ___ should be used instead of npm install in CI for deterministic builds.

Q4. Single choice: Which step must usually come first in a GitHub Actions job?

• A. npm run build
• B. npm test
• C. actions/checkout@v4
• D. npm run deploy

Q5. Debugging: Your workflow says command not found: eslint. Name three likely causes.

Q6. Scenario: Your YAML file fails to parse. The error says “mapping values are not allowed here.” What do you check first?

Q7. Matching: Match each concept to its meaning.

Q8. True/False: Tabs are acceptable in YAML workflow files.

Q9. Scenario: You push to a branch called feature/login, but your workflow only triggers on push: branches: [main]. Will the workflow run?

Q10. Fill in the blank: To trigger a workflow on every pull request, use on: _______.

Junior (Level 2)

Q11. Multiple choice: Why use a matrix strategy?

• A. To hide secrets
• B. To run the same job across multiple versions or platforms
• C. To make logs shorter
• D. To replace caching

Q12. True/False: The needs keyword can control the execution order of jobs.

Q13. Fill in the blank: The cache key should usually be tied to the ____.

Q14. Scenario: A pull request workflow should NOT deploy to production. Write the condition.

Q15. Debugging: A job passes locally but fails in CI with missing peer dependencies. What should you inspect?

Q16. Matching: Match the package manager to its lockfile and cache mode.

Q17. Single choice: Which is a common anti-pattern?

• A. Parallel jobs for lint and test
• B. Reusable workflows
• C. Duplicating nearly identical YAML in every repository
• D. Protected environments

Q18. Scenario: Your team wants preview deployments for every PR. What trade-offs should be discussed?

Q19. True/False: actions/setup-node with cache: npm caches the node_modules directory.

Q20. Fill in the blank: To access a secret named DEPLOY_KEY in a step, use ${{ secrets.________ }}.

Senior / Expert (Level 3–4)

Q21. Multiple choice: What is the biggest advantage of OIDC over long-lived cloud access keys?

• A. Faster YAML parsing
• B. Short-lived, federated credential exchange — no static keys to leak
• C. Better log formatting
• D. More matrix options

Q22. True/False: Blue-green deployment always uses less infrastructure than rolling deployment.

Q23. Fill in the blank: A workflow reused across repositories via workflow_call is called a ____ workflow.

Q24. Scenario: Your monorepo has 150 packages. Path filters in on.push.paths miss changes to shared packages. What strategy would you use?

Q25. Debugging: Deployment succeeded, but the app is broken because a database migration failed halfway. What design mistake likely occurred?

Q26. Single choice: Which is most appropriate for sharing step-level logic (like checkout + install + setup)?

• A. Composite action
• B. Release tag
• C. Pull request template
• D. Artifact retention policy

Q27. Multiple choice: Which is a good reason to use self-hosted runners? (Select all)

• A. No maintenance required ever
• B. Private network access and custom tooling
• C. Avoid writing workflows
• D. Cost control at scale

Q28. Matching: Match each deployment strategy to its description.

Q29. Scenario: An action from the marketplace (cool-deploy@latest) suddenly starts exfiltrating secrets. What policy would have prevented this?

Q30. Real-world pain: CI costs have doubled after adding matrix tests across 3 OS × 3 Node versions (9 combinations). How would you evaluate whether the extra coverage is worth the cost?

Q31. True/False: Scheduled workflows can trigger on any branch.

Q32. Fill in the blank: Production secrets should be stored in a GitHub ____ with protection rules.

Q33. Design question: How would you design rollback for a system that uses feature flags AND database migrations?

Q34. Debugging: A workflow that depends on an environment secret works in staging but fails in production with “secret not found.” What should you inspect?

Q35. Design question: When should a team move from per-repo YAML files to organization-wide reusable workflows?

8. Personalized Recommendations

Based on your stack: React, Next.js, Astro, TypeScript, static files

Patterns most useful for you

1. PR validation workflow: lint + typecheck + test + build on every PR. This is your #1 quality gate.
2. Dependency caching: actions/setup-node with cache: npm (or pnpm). Essential for speed.
3. Preview deployments: Automatic preview URLs for every PR (via Vercel or Cloudflare).
4. Production deployment with environment protection: Deploy on merge to main, with approval for production.
5. Path filters: For monorepos or multi-package setups, skip CI for unrelated changes.
6. Concurrency cancellation: Cancel in-progress runs when you push again to the same PR.
7. Dependabot auto-merge: Automatically merge safe patch updates that pass CI.
8. Release automation: Automated versioning and changelog generation on merge.

What to learn first (priority order)

1. Basic workflow syntax and structure.
2. Triggers: push, pull_request, workflow_dispatch.
3. actions/checkout + actions/setup-node + npm ci.
4. Multi-job pipelines with needs.
5. Caching.
6. Secrets and environments.
7. Conditional logic with if:.
8. Artifacts.
9. Reusable workflows.
10. OIDC and security hardening.

Which workflows to build first

Mistakes frontend engineers commonly make in CI/CD

How to evolve from simple to production-grade

Phase 1: Single-job CI
  └── lint + test + build in one job

Phase 2: Multi-job CI
  └── parallel lint/typecheck/test → build

Phase 3: Deployment
  └── CI → staging deploy → production deploy

Phase 4: Safety
  └── environment protection, secrets, branch rules

Phase 5: Speed
  └── caching, concurrency, path filters

Phase 6: Automation
  └── Dependabot, release automation, auto-labeling

Phase 7: Reuse
  └── composite actions, reusable workflows

Phase 8: Security
  └── OIDC, action pinning, CodeQL, dependency review

Phase 9: Observability
  └── notifications, failure alerts, cost tracking

Phase 10: Platform
  └── org-wide shared workflows, governance, runner fleet

30-day learning plan

Week 1: Foundations (Days 1–7)

Week 2: Team workflows (Days 8–14)

Week 3: Production readiness (Days 15–21)

Week 4: Advanced patterns (Days 22–30)