Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 44 ยท GitHub Actions in Practice

CI for Node and Python Projects

Build a complete CI workflow for Node.js and Python: checkout, setup actions, cached installs, lint, tests, coverage upload, version matrices and concurrency.

Continuous integration for a typical Node.js or Python project is the same short story every time: get the code, install a language runtime, install dependencies, check style, run the tests, keep the reports. The syntax is different from the basics you already know, but the shape is stable enough that once you can write one such workflow, you can write the other in minutes.

This lesson builds both workflows step by step and then adds the three upgrades real projects need: a version matrix, a cancel-old-runs rule and a coverage upload. The YAML is read-only because it needs GitHub to run it. The runnable example is a stand-in: a tiny test runner that does what npm test or pytest do at the end of the pipeline, which is to turn failed checks into a non-zero exit code that GitHub reads as a red job.

The shape of a CI job

flowchart LR
  A["Checkout"] --> B["Set up runtime<br/>+ cache"]
  B --> C["Install<br/>dependencies"]
  C --> D["Lint"]
  D --> E["Test<br/>+ coverage"]
  E --> F["Upload<br/>reports"]

Each step must succeed for the next one to run; the first failure turns the job red.

Order matters for feedback. Linting is fast, so it runs before the slower tests. If you want the two to run in parallel and finish sooner, split them into separate jobs, as in Jobs, Steps and Dependencies. For a small project one job is simplest and cheapest.

A Node.js workflow

YAML
name: Node CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage

      - uses: actions/upload-artifact@v4
        if: matrix.node == 22
        with:
          name: coverage
          path: coverage/
          retention-days: 14

Go through it from the top:

  • on runs the workflow for pushes to main and for every pull request. Triggers covers filters in detail.
  • permissions: contents: read gives the automatic token the least it needs, as explained in Secrets, Variables and Environment Variables.
  • timeout-minutes stops a hung test run from burning minutes.
  • actions/checkout copies the repository onto the runner. Without it, the machine has an empty folder.
  • actions/setup-node installs the requested Node.js version and, with cache: npm, caches npm's download folder keyed by package-lock.json. See Caching and Artifacts. You can also read the version from a file with node-version-file: .nvmrc, so local development and CI agree.
  • npm ci installs exactly what the lock file says and fails if package.json and the lock file disagree. It is faster and stricter than npm install, which makes it the right command for CI.
  • npm run lint and npm test run scripts defined in package.json. Any non-zero exit code fails the step.
  • The coverage upload uses if: matrix.node == 22 so only one matrix job uploads, avoiding the name conflicts described in the caching lesson.

A Python workflow

YAML
name: Python CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        python: ["3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
          cache: pip

      - run: python -m pip install --upgrade pip
      - run: pip install -r requirements.txt -r requirements-dev.txt

      - run: ruff check .
      - run: pytest --cov=app --cov-report=xml

      - uses: actions/upload-artifact@v4
        if: matrix.python == '3.12'
        with:
          name: coverage-xml
          path: coverage.xml

Notice the quotes around "3.11". Without them YAML reads 3.10 as the number 3.1 and the job would try to install the wrong interpreter; YAML for Pipeline Authors explains the trap. The cache: pip option hashes your requirements files to decide when to refresh the cache. Use python -m pip rather than a bare pip so you are sure which interpreter's pip you are calling. Some teams prefer a virtual environment or a tool such as uv; the pipeline stays the same: install from a pinned file, then lint, then test.

The linter here is ruff and the test tool is pytest with the pytest-cov plugin. You could equally use flake8, black in check mode, or unittest. The CI part is only "run the command your team already runs locally."

Concurrency: cancel the obsolete run

Push three commits to a branch in a minute and you get three runs, though only the last matters. The concurrency block fixes that:

YAML
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Runs that share a group string are limited to one at a time, and cancel-in-progress: true cancels the older one when a new one starts. The group is built from the workflow name and the branch (github.ref), so different branches and different workflows never cancel each other. A common refinement is to cancel only on pull requests, so that runs on main always finish:

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

Never put a deployment into a group that cancels in-progress runs without thinking: cancelling a deploy halfway can leave a server half updated. For deploys, use a group without cancellation, which queues instead.

Making failures useful

A red job is only useful if it tells you what broke. Keep these habits:

  • Run the same commands locally. If npm test passes on your laptop but fails in CI, compare Node versions and lock files first. Pin versions with the matrix or .nvmrc so there are no surprises.
  • Fail loudly and early. Do not add continue-on-error to lint or test steps just to make the job green.
  • Keep reports. Upload coverage and test reports with if: always() so you still have them after failure. Test Stages in a Pipeline goes deeper.
  • Do not store secrets in test code. Tests that need them should use dummy values; real tokens belong to deploy jobs.

Stand-in: a tiny test runner and its exit code

GitHub decides pass or fail from the process exit code: 0 is success, anything else is failure. The program below is a miniature test runner. It runs named checks, prints a report like a real tool does and sets process.exitCode. It runs on this site's Node.js server. Make a test fail on purpose by editing an expected value, then look at the last line.

Node.js A mini test runner that sets the exit code

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Because the exit code is 1, a real CI step running this program would be marked failed, and the steps after it (unless they use if: always()) would be skipped. Change 5 to 4 to turn the run green.

Stand-in: a pipeline that stops at the first failing step

The second model mirrors the workflow above. Each step is a function returning an exit code. The runner executes steps in order, stops at the first non-zero code, and still runs steps marked always, as an artifact upload would.

Node.js Steps, exit codes and if: always()

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

This is the same logic you saw in Expressions and Contexts: the default condition is success(), and always() overrides it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why use npm ci instead of npm install in a CI job?

    npm ci is built for automation: it uses the lock file as is, starts from a clean node_modules and errors if the lock file and package.json disagree.
  2. 2. Why should a Python version in a matrix be written as "3.10" in quotes?

    An unquoted 3.10 is a float, which becomes 3.1, an old and different Python version.
  3. 3. What makes a test step fail in GitHub Actions?

    GitHub only looks at the exit code. A tool that prints errors but exits with 0 would not fail the job.
  4. 4. What does cancel-in-progress: true do with a group of ${{ github.workflow }}-${{ github.ref }}?

    Runs with the same group string are serialized, and the older in-progress one is cancelled. Other branches and workflows have different groups.
  5. 5. Why does the coverage upload step use if: matrix.node == 22?

    Every matrix job would otherwise upload an artifact called coverage, and names must be unique within a run.

Summary

  • A CI job for Node or Python is: checkout, set up the runtime with caching, install from the lock or requirements file, lint, test with coverage, upload reports.
  • Use npm ci and pinned versions; quote Python versions such as "3.12".
  • A matrix tests several runtime versions; upload shared artifacts from only one matrix entry or give each a unique name.
  • concurrency with cancel-in-progress saves minutes by cancelling obsolete runs; do not use it to cancel deployments.
  • Pass or fail is the exit code of each command, and if: always() keeps reports after failures.

Next: CI for Java, Go and PHP Projects