Chapter 4 — CI/CD with GitHub Actions

The why

Every push to main should trigger a gauntlet: lint, test, build, and — if everything passes — deploy. GitHub Actions makes this automatic, free (within limits), and defined as code right next to your application.

Core concepts

What GitHub Actions is

GitHub Actions is an automation platform built into GitHub. You define workflows — sequences of jobs triggered by events (push, pull request, schedule, manual trigger). Each job runs on a fresh virtual machine (runner) and executes steps: shell commands or reusable actions from the marketplace.

Key facts:

• Free tier: 2,000 minutes/month for private repos, unlimited for public repos.
• Runners: Ubuntu, Windows, or macOS VMs. Or self-hosted on your own hardware.
• Defined as code: Workflows live in .github/workflows/*.yml — version-controlled, reviewed, and branched alongside your application code.

Anatomy of a workflow file

name: CI Pipeline
 
# ---- When does it run? ----
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
# ---- What jobs does it run? ----
jobs:
  # Job 1: Lint and type-check
  lint:
    name

Let's break down every section.

Triggers: on

The on block defines what events kick off the workflow. You can combine multiple triggers:

on:
  # On push to specific branches
  push:
    branches: [main, develop]
    tags: ['v*']          # Also on version tags like v1.0.0
 
  # On pull requests targeting main
  pull_request:
    branches: [main]
    types: [opened

Jobs and steps

A job is a unit of work that runs on a single runner. A step is an individual command or action within a job.

jobs:
  my-job:
    runs-on: ubuntu-latest    # Runner type
    timeout-minutes: 10       # Kill if it takes longer
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Run a command
        run: echo "Hello"
        shell: bash
 
      - name

Jobs run in parallel by default. Use needs to create dependencies:

jobs:
  lint:
    # Runs immediately
 
  test:
    # Runs immediately, parallel with lint
 
  build:
    needs: [lint, test]   # Waits for BOTH lint AND test to succeed
 
  deploy:
    needs: [build]         # Waits for build

This creates a pipeline:

lint ──┐
       ├── build ── deploy
test ──┘

Actions: The reusable building blocks

Actions are the npm packages of CI/CD. Instead of writing complex logic yourself, you use community or official actions:

steps:
  # Checkout your code (THE most-used action)
  - uses: actions/checkout@v4
 
  # Set up Node.js
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: 'npm'
 
  # Set up Docker Buildx (for multi-platform builds)
  - uses: docker/setup-buildx-action@v3
 
  # Login to Docker Hub

Always pin actions to a major version (@v4) for stability. The action author can ship non-breaking updates to the major version tag.

Secrets and environment variables

Secrets are encrypted values stored in GitHub (Settings → Secrets and variables → Actions). They're injected at runtime and never appear in logs:

steps:
  - name: Deploy
    env:
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    run: |
      echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
      chmod 600 ~/.ssh/id_rsa
      scp -r dist/ user@${{ secrets.SERVER_IP }}:/opt/app/

Caching: Don't download the internet every time

Without caching, every CI run downloads dependencies from scratch. actions/setup-node@v4 has built-in caching:

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: 'npm'           # Automatically caches ~/.npm

For other caching needs (e.g., Docker layers, build outputs):

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

The cache key strategy: if package-lock.json hasn't changed, the exact key matches and you get a cache hit. If it has changed, restore-keys provides a partial match (same OS, different lockfile). This saves 30-90% of CI time.

Matrix builds: Test across multiple versions

You want to know your code works on Node 18, 20, AND 22 — not just the one you develop on. Matrix builds run the same job with different parameters:

jobs:
  test:
    name: Test (Node ${{ matrix.node-version }})
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
        # Can add more dimensions:
        # os: [ubuntu-latest, windows-latest]
        # db: [postgres, mysql]
    steps:
      - uses:

This spawns 3 parallel jobs — one for each Node version. If Node 22 tests pass but Node 18 fails, you've found a compatibility bug before your users did.

Environment branches: Staging vs Production

Real pipelines have multiple environments. Use environment protection rules:

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    if: github.ref == 'refs/heads/develop'
    steps:
      - run: ./deploy.sh staging
 
  deploy-production:
    runs-on: ubuntu-latest
    environment: production
    if: github.ref == 'refs/heads/main'
    needs: [deploy-staging]
    steps:
      -

Environment protection rules (configured in GitHub repo settings):

• Required reviewers: Someone must approve before the deploy job runs.
• Wait timer: Deploy is delayed by N minutes (gives you time to abort).
• Protected branches: Only specific branches can deploy to this environment.
• Environment secrets: Secrets scoped to this environment only (production API keys different from staging).

Artifacts: Passing data between jobs

Each job runs on a fresh runner. To pass build output from one job to another, use artifacts:

jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7
 
  deploy:
    needs: [build]
    steps:
      - uses: actions/download-artifact@v4

A complete production pipeline

Let's put it all together — a real-world CI/CD workflow for a Dockerized Node.js app:

name: Build, Test & Deploy
 
on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  #

This pipeline:

1. Runs linting + type checking.
2. Runs tests across 3 Node versions with a real PostgreSQL service container.
3. Builds a Docker image and pushes it to GitHub Container Registry (ghcr.io).
4. SSHes into the production server, pulls the new image, and restarts the container.

Real-world example: How a SaaS team catches bugs before they reach users

A project management SaaS with 15 developers was deploying to production 3-4 times a day. Before GitHub Actions, their "pipeline" was:

1. Developer pushes to main.
2. Someone manually runs npm test on their machine (if they remember).
3. Someone SSHes into the server, git pull, npm install, pm2 restart.

Problems:

• Tests would pass on the developer's machine but fail on another's (different Node version).
• Someone would forget to run tests before deploying. Broken code reached users.
• Deployments took 15 minutes of manual work, so people deployed less often (bigger, riskier changes).
• Rollbacks were painful — "which commit was the last good one?"

They implemented the pipeline above. Results after 3 months:

• Zero failed deploys. Every commit to main went through lint → test (3 Node versions) → build → deploy. Any failure blocked the pipeline.
• Deploy time dropped from 15 min to 90 seconds. All automated.
• Matrix testing caught 4 bugs before they reached users — issues that only appeared on Node 18 but not Node 22.
• Rollbacks became instant. The previous Docker image was still on the server. One command to switch back.
• Developers deployed 8-10 times a day instead of 3-4. Smaller, safer changes.

The key insight: CI/CD isn't just about speed — it's about making the right thing (testing before deploy) the easy thing (automatic), and the wrong thing (skipping tests) impossible.

Common mistakes

Production notes

• Use github.ref and github.event_name for conditional logic. Deploy only from main, not from feature branches. Preview deploys from PR branches if you have the infrastructure.
• Add a concurrency group to prevent race conditions. concurrency: group: ${{ github.workflow }}-${{ github.ref }} ensures only one workflow runs per branch at a time. A new push cancels the in-progress run for the same branch.
• Use OpenID Connect (OIDC) instead of long-lived cloud credentials. Instead of storing AWS access keys as secrets, configure OIDC so GitHub Actions can assume an IAM role directly — no static credentials to rotate or leak.
• Monitor workflow run duration. If CI suddenly goes from 3 minutes to 12 minutes, investigate — it's usually a caching regression or a new slow test.

Performance notes

• Cache Docker layers with GitHub Actions cache. cache-from: type=gha and cache-to: type=gha,mode=max in docker/build-push-action saves minutes per build.
• Use paths filters to skip irrelevant workflows. If only docs changed, don't run the full test suite: on: push: paths: ['src/**', 'package.json', 'package-lock.json'].
• Restore partial cache matches. The restore-keys in actions/cache lets you reuse a cache even when the primary key doesn't match exactly — partial hits are better than cache misses.
• Service containers vs docker compose. For simple services (PostgreSQL for tests), use services: in the job definition. It's faster than docker compose up because the runner manages the lifecycle.

Security notes

• Never use pull_request_target for untrusted code. This event runs in the context of the BASE repository (access to secrets) even for PRs from forks. Attackers can exfiltrate secrets. Use pull_request (lowercase) which runs in the fork's context.
• Review third-party actions before pinning them. An action has access to your repo and secrets. Prefer official actions (actions/*, github/*, docker/*) and well-known community actions.
• Use GITHUB_TOKEN with minimal permissions. Add permissions: block at the workflow or job level: contents: read is enough for most jobs; only packages: write for Docker push jobs.
• Rotate deploy keys and SSH keys periodically. Even if they're stored as secrets, credentials can leak through log output or misconfigured workflows.

Exercises

Beginner:

1. Create a .github/workflows/ci.yml that runs on every push to main. It should checkout code, set up Node.js, install dependencies, and run npm test. Push it and verify the workflow runs in the Actions tab.
2. Add a lint step to your workflow. Make it fail intentionally (introduce a linting error), push, and observe the workflow failing. Fix the error and see it pass.

Intermediate:

1. Create a matrix build that tests your code on Node.js 18, 20, and 22. Add a service container (PostgreSQL) for integration tests. Use fail-fast: false. Verify all 3 jobs complete even if one fails.
2. Add Docker build and push to your pipeline. Build a Docker image, tag it with the commit SHA, and push it to GitHub Container Registry. Add caching for Docker layers.

Advanced:

1. Build a complete CI/CD pipeline: lint → test (matrix) → build Docker image → deploy to staging (automatic) → deploy to production (requires manual approval via environment protection rules). Add concurrency groups, timeout-minutes, and artifact passing.
2. Set up OIDC authentication to deploy to AWS (or any cloud provider). Replace static access key secrets with OIDC-based role assumption. Document the GitHub-side and cloud-side configuration.

Interview questions

Beginner:

1. Q: What is CI/CD? A: CI (Continuous Integration) is the practice of automatically building and testing code every time it's pushed to a shared repository. CD (Continuous Delivery/Deployment) extends that to automatically deploying passing builds to staging or production. The goal: catch problems early, deploy safely and frequently.

2. Q: What's the structure of a GitHub Actions workflow file? A: A YAML file with name, on (triggers), and jobs. Each job has runs-on (runner type), steps (commands or actions), and optional needs (dependencies). Jobs without needs run in parallel; jobs with needs wait for their dependencies to succeed.

3. Q: How do you pass secrets to a GitHub Actions workflow? A: Store them in GitHub Settings → Secrets and variables → Actions. Reference them in the workflow with ${{ secrets.SECRET_NAME }}. Secrets are encrypted at rest and automatically redacted from logs.

Senior:

1. Q: How do you design a CI/CD pipeline that prevents broken code from reaching production while keeping deploy times under 5 minutes? A: Layer the pipeline by speed and criticality: (1) Fast checks first — linting, formatting, type checking (1-2 min). These catch 80% of issues. (2) Unit tests run in parallel with matrix builds (2-3 min). (3) Integration tests with service containers (3-4 min). (4) Build Docker image with layer caching (1-2 min). (5) Deploy to staging automatically, run smoke tests (1 min). (6) Production deploy gated by manual approval or automated canary analysis. Use caching aggressively (npm, Docker layers, build artifacts). Skip irrelevant jobs with paths: filters. Set concurrency to cancel redundant runs. The key insight: developers should get feedback on lint/test failures within 2 minutes; the full pipeline completes in under 5 minutes for most changes.

2. Q: What's the security risk of pull_request_target vs pull_request, and when would you use each? A: pull_request_target runs in the context of the BASE repository — it has access to repository secrets and write permissions, even for PRs from forks. This is dangerous: a malicious PR from a fork could exfiltrate secrets or modify the repo. Only use pull_request_target for workflows that need secret access AND you've explicitly checked out the PR code safely (e.g., labeling PRs, commenting). pull_request runs in the fork's context with read-only access to the base repo — safe for building and testing PR code. For 95% of cases, use pull_request. Use pull_request_target only for trusted automation that doesn't execute PR code (e.g., ).

Summary

GitHub Actions automates your quality gates and deployments, defined as YAML workflows living right alongside your code. A workflow triggers on events (push, PR, schedule, manual), runs jobs in parallel or sequence, and executes steps — shell commands or reusable community actions. Secrets are encrypted and injected at runtime. Caching (npm, Docker layers, build artifacts) turns 10-minute pipelines into 2-minute ones. Matrix builds test your code across multiple Node versions, operating systems, and database versions simultaneously. Environment protection rules gate production deploys behind manual approval. The complete pattern: lint → test (matrix) → build Docker image → deploy to staging automatically → deploy to production with approval. CI/CD isn't about speed alone — it makes the right thing (testing before deploy) automatic and the wrong thing (skipping tests) impossible.

Quick recall

• Workflow file: .github/workflows/*.yml — YAML with name, on, jobs.
• Triggers: push, pull_request, schedule (cron), workflow_dispatch (manual).
• Jobs: Run in parallel by default. needs: [jobA, jobB] creates dependencies.
• Steps: uses: (actions) or run: (shell commands).
• Secrets: ${{ secrets.NAME }} — stored in GitHub, redacted from logs.
• Caching: actions/cache@v4 or built-in cache: 'npm' in setup-node.
• Matrix: strategy: matrix: node-version: [18, 20, 22] — parallel jobs per combination.
• Artifacts: / — pass data between jobs.

Quiz

1. What file extension do GitHub Actions workflow files use? Answer: .yml (or .yaml), stored in .github/workflows/.
2. How do you make one job wait for another job to complete? Answer: Use needs: [other-job-name] in the dependent job definition.
3. Where should you store API keys and passwords for use in workflows? Answer: In GitHub Settings → Secrets and variables → Actions, referenced as ${{ secrets.SECRET_NAME }}.
4. What's the purpose of a matrix build? Answer: To run the same job with multiple parameter combinations (Node versions, OS, databases) in parallel to catch compatibility issues.
5. Why should you use fail-fast: false in a matrix strategy? Answer: So that one failing matrix job doesn't cancel all others — you want to see which specific combinations fail.
6. What's the difference between pull_request and pull_request_target? Answer: pull_request runs in the fork's context without secret access (safe for PRs from forks). pull_request_target runs in the base repo's context with secret access (dangerous — only for trusted automation).
7. How do you set a time limit on a job to prevent runaway processes from burning all your CI minutes? Answer: timeout-minutes: 15 in the job definition.