Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Testing and CI

GitHub Actions for Python Projects

Set up continuous integration for a Python package with GitHub Actions. Learn workflows, jobs, matrices, caching, artifacts and permissions, and check a workflow with code.

Tests that only run on your laptop protect only you. Continuous integration (CI) runs your checks automatically on a clean machine every time someone pushes code or opens a pull request. If you host on GitHub, GitHub Actions is the built-in CI system: a YAML file in your repository describes what to run and when.

This lesson builds a complete workflow for a Python package step by step: lint, test across Python versions, build the distribution, and keep everything fast and safe. Workflows only run on GitHub, so the YAML is shown read-only, and the runnable example parses and checks a workflow file with real code.

Anatomy of a workflow

Workflows live in .github/workflows/*.yml. The vocabulary is small:

  • A workflow is one YAML file, started by an event (push, pull_request, a schedule, a release).
  • A workflow has one or more jobs. Jobs run in parallel on separate machines (runners) unless one declares needs: other-job.
  • A job is a list of steps. A step either runs a shell command (run:) or uses a reusable action (uses:).
flowchart LR
    E["push / pull_request"] --> L["job: lint"]
    E --> T["job: test<br/>matrix: 3 Python versions"]
    L --> B["job: build"]
    T --> B
    B --> A["artifact: dist/"]

Lint and test run in parallel; build waits for both.

A complete CI workflow

YAML
name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv run ruff check .
      - run: uv run ruff format --check .

  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        python: ["3.10", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: ${{ matrix.python }}
          enable-cache: true
      - run: uv sync --frozen
      - run: uv run coverage run -m pytest
      - run: uv run coverage report

  build:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

Check the current major versions of each action before copying (@v4 and so on change over time); the structure stays the same. If you prefer pip, replace the setup action with actions/setup-python (and its cache: pip option) and run pip install -e ".[test]".

What each part does

  • on: chooses events. pull_request runs on proposed changes; push to main runs after merging. Add workflow_dispatch: for a manual "Run workflow" button and schedule: with a cron string for nightly runs (useful for catching new dependency releases).
  • permissions: contents: read gives the automatic GITHUB_TOKEN the least access it needs. Grant more per job only when required (for example id-token: write for trusted publishing).
  • concurrency cancels an older run of the same branch when a new push arrives, saving minutes.
  • matrix multiplies a job: here 2 operating systems times 3 Python versions makes 6 test jobs. fail-fast: false lets the other cells finish even if one fails, which tells you whether a problem is specific to one platform.
  • needs orders jobs; build starts only after lint and test succeed.
  • Artifacts (upload-artifact) keep files such as the built wheel so later jobs or humans can download them.

Speeding it up

Installing dependencies on every run is wasteful. Cache them:

  • astral-sh/setup-uv with enable-cache: true caches uv's download cache and keys it on your lock file.
  • actions/setup-python has cache: pip (or poetry, pipenv) which keys on requirements or lock files.
  • Run independent jobs in parallel and keep jobs small.
  • Skip work that cannot be affected: paths: filters on an event can skip the workflow when only documentation changed (careful: required checks must still report a status).

Security habits

Workflows run code on your behalf, and some of them can publish packages, so treat them like production code.

  1. Least privilege. Set permissions at the top, grant more to single jobs only.
  2. Pin third-party actions by commit SHA for sensitive workflows (uses: owner/action@<full-sha> # v4.1.0). A tag can be moved to different code; a SHA cannot.
  3. Never put secrets in logs or in pull request workflows from forks. Pull requests from forks do not receive secrets by default; do not weaken that with pull_request_target unless you really understand it.
  4. Avoid long-lived tokens. Prefer OpenID Connect (OIDC) so the registry trusts the workflow's identity, rather than a stored password.
  5. Keep Actions updated with Dependabot (package-ecosystem: "github-actions").

Checking a workflow with code

A broken workflow file fails silently or with confusing messages. You can lint a workflow yourself: parse the YAML, verify that every needs points at a real job, compute the matrix size and the order jobs will run in.

Python Validate a workflow file

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 input()), it gets the next line from this box.

The comment about on is a real gotcha: YAML 1.1 parsers, including PyYAML, turn an unquoted on key into the boolean True. GitHub reads the file correctly, but your own tooling must handle it.

Practical advice

  • Make CI run the same commands developers run locally (uv run pytest, tox, nox), ideally through one script or task, so a failure reproduces on your machine.
  • Treat a red build as urgent; broken main branches teach everyone to ignore CI.
  • Mark the important jobs as required status checks in the branch protection settings, so a pull request cannot merge while they fail.
  • Run a scheduled build against the latest dependency versions to hear about breakage early.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does needs: [lint, test] on the build job do?

    needs defines job ordering. Without it, jobs run in parallel.
  2. 2. Why set permissions at the top of the workflow?

    The principle of least privilege limits what a compromised or mistaken step can do.
  3. 3. How many test jobs does os: [ubuntu, windows] with python: ["3.10", "3.12", "3.13"] create?

    A matrix multiplies its axes, so 2 times 3 gives 6 jobs.
  4. 4. Why pin a third-party action to a commit SHA in sensitive workflows?

    A tag is a movable label. Pinning the SHA ensures the code you reviewed is the code that runs.

Summary

  • A workflow is YAML in .github/workflows; events start it, jobs run in parallel on runners, steps run commands or actions.
  • Matrices multiply jobs across Python versions and operating systems; needs orders jobs.
  • Cache dependencies, cancel superseded runs with concurrency, and keep CI commands identical to local ones.
  • Use least-privilege permissions, pinned actions and OIDC instead of long-lived secrets.
  • Workflows are code: validate and review them.

Next: Release Automation and Trusted Publishing