Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Projects and Practice

Project: A Complete CI Pipeline

Build a complete continuous-integration pipeline for a Node project with GitHub Actions: lint, test matrix, caching, coverage artifacts, a required gate job and a runnable plan checker.

In this project you put the whole Actions chapter to work. You will design a CI pipeline for a small Node.js library that runs on every pull request, fails fast on mistakes, finishes in a few minutes, and gives reviewers one clear "ready to merge" signal. The same structure transfers to Python, Java or Go; only the commands change.

The workflow files are read-only here, because GitHub is not available on this site. A stand-in at the end checks a pipeline plan against our design goals.

Goals

A good CI pipeline is:

  • Fast. Developers wait for it. Use caching, parallel jobs and path filters.
  • Reliable. The same commit gives the same result. Pin versions, use npm ci.
  • Clear. One required check means one thing to look at.
  • Safe. Minimal token permissions, no secrets for untrusted code, pinned actions.
  • Cheap. Cancel superseded runs, set timeouts, avoid needless matrix cells.

The repository

Assume a library with package.json scripts lint, test and build, a lock file, and source in src/. The pipeline lives in .github/workflows/ci.yml.

Step 1: triggers, permissions and concurrency

YAML
name: CI

on:
  pull_request:
  push:
    branches: [main]
  merge_group:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Read-only permissions by default. The concurrency group cancels an older run when a newer commit lands on the same pull request, but never cancels runs on main. merge_group makes the workflow usable with a merge queue.

Step 2: lint job

YAML
jobs:
  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint

cache: npm uses the dependency cache keyed on the lock file. Lint finishes quickly, so style mistakes are reported long before the slow tests.

Step 3: test matrix

YAML
  test:
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22, 24]
        exclude:
          - os: windows-latest
            node: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        if: matrix.os == 'ubuntu-latest' && matrix.node == 22
        with:
          name: coverage
          path: coverage/
          retention-days: 7

The matrix runs five cells. fail-fast: false shows every failing combination in one run instead of cancelling the rest. Only one cell uploads the coverage report, because artifact names must be unique in a run in v4 of the upload action.

Step 4: build job

YAML
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm pack --dry-run

Building separately proves the package can actually be produced, and npm pack --dry-run lists what would be published, which catches accidentally missing or extra files.

Step 5: one gate for the branch rule

Required checks are listed by job name. A matrix makes five names, and renaming a cell would silently remove protection. The common solution is a final gate job that depends on everything and is the only required check:

YAML
  ci-ok:
    if: ${{ always() }}
    needs: [lint, test, build]
    runs-on: ubuntu-latest
    steps:
      - name: Fail if any needed job failed or was cancelled
        run: |
          if [ "${{ contains(needs.*.result, 'failure') }}" = "true" ] || [ "${{ contains(needs.*.result, 'cancelled') }}" = "true" ]; then
            echo "A required job did not pass"
            exit 1
          fi

if: always() makes the gate run even when a dependency fails; without it a failed needed job would skip the gate, and a skipped required check can look like a pass in some setups. Now mark ci-ok as the single required status check in your ruleset.

Step 6: keep it healthy

  • Add Dependabot for npm and github-actions (Dependabot).
  • Add a CodeQL workflow on a schedule.
  • Pin third-party actions to commit SHAs (supply-chain safety).
  • Add path filters only if you also keep the gate honest (a skipped workflow cannot report the required check).
  • Watch run duration on the Actions tab; if tests grow slow, shard them with a matrix index.
flowchart LR
  P["Pull request"] --> L["lint"]
  P --> T["test matrix"]
  P --> B["build"]
  L --> G["ci-ok gate"]
  T --> G
  B --> G
  G --> M["Merge allowed"]

Three parallel jobs feed one gate; the ruleset requires only the gate.

A stand-in: grade a pipeline plan

The checker below reads a simplified description of a pipeline and reports how it measures up against the goals. It is a classroom exercise we wrote, not a real linter: it works on a plain object, not on YAML, and only looks at a few signals.

JS Stand-in: CI plan grader (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Fix the plan object until you reach 7/7: that is the checklist for your real workflow too.

Extensions to try

  1. Add a workflow that comments the coverage percentage on the pull request using GITHUB_TOKEN with pull-requests: write.
  2. Turn the shared steps into a composite action (.github/actions/setup-project).
  3. Publish a preview of the docs on every pull request using Pages.
  4. Add a nightly run with schedule against the newest Node version, so you hear about breakage early.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why add a single gate job that depends on all other jobs?

    A gate keeps the ruleset simple and robust against changes in the job list.
  2. 2. What does if: always() on the gate job ensure?

    Without it, a failed dependency would skip the gate, hiding the failure from the required check.
  3. 3. Why should only one matrix cell upload the coverage artifact?

    Several cells uploading the same artifact name would conflict.
  4. 4. What does cancel-in-progress do on pull request runs?

    Only the latest commit matters for review, so older runs are cancelled to save minutes.

Summary

  • Build CI as parallel jobs (lint, test matrix, build) with read-only permissions, caching, timeouts and concurrency control.
  • Use one always-running gate job as the single required check.
  • Keep the pipeline healthy with Dependabot, scanning and pinned actions.

Next: Project: Set Up an Open-Source Repository