GitHub Actions CI for Python with Matrix Testing

Advanced20 min

Set up a complete GitHub Actions CI pipeline for Python projects with matrix testing across multiple Python versions, linting, type checking, and coverage.

Prerequisites

-A Python project in a GitHub repository
-pytest and ruff installed as dev dependencies

Steps

Create the CI workflow directory

Create the directory structure that GitHub Actions requires for workflow files.

$ mkdir -p .github/workflows

Create the CI workflow file

Create a CI workflow that tests against Python 3.11, 3.12, and 3.13. It runs linting, formatting checks, type checking, and tests with coverage.

$ cat > .github/workflows/ci.yml << 'EOF' name: CI on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ['3.11', '3.12', '3.13'] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - run: pip install -r requirements.txt - run: pip install pytest pytest-cov ruff mypy - run: ruff check . - run: ruff format --check . - run: mypy src/ --ignore-missing-imports - run: pytest --cov=src --cov-report=xml tests/ EOF

The matrix strategy runs all Python versions in parallel, so the total CI time equals the slowest single version, not the sum.

Validate the workflow syntax locally

Verify that the workflow file is valid YAML before committing. Syntax errors in workflow files are only caught after pushing to GitHub.

$ python -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))" && echo 'Valid YAML'

This checks YAML syntax only, not GitHub Actions schema. For full validation, use 'actionlint' if installed.

Commit and push the workflow

Commit the workflow file and push to GitHub. The CI pipeline will trigger automatically on the next push or pull request to main.

$ git add .github/workflows/ci.yml && git commit -m 'ci: add Python CI pipeline' && git push

Check the workflow run status

Use the GitHub CLI to check the status of recent workflow runs. This shows whether your CI pipeline passed or failed.

$ gh run list --limit 5

Use 'gh run view <run-id> --log-failed' to see the logs for a failed run without opening a browser.

Full Script

full-script.sh

#!/bin/bash
# GitHub Actions CI setup for Python
set -e

mkdir -p .github/workflows

cat > .github/workflows/ci.yml << 'WORKFLOW'
name: CI

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install ruff
      - run: ruff check .
      - run: ruff format --check .

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: pip install mypy
      - run: mypy src/ --ignore-missing-imports

  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.11', '3.12', '3.13']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: pip install -r requirements.txt
      - run: pip install pytest pytest-cov
      - run: pytest --cov=src --cov-report=xml --cov-fail-under=80 tests/
      - uses: actions/upload-artifact@v4
        if: matrix.python-version == '3.12'
        with:
          name: coverage-report
          path: coverage.xml
WORKFLOW

echo "CI workflow created at .github/workflows/ci.yml"
echo "Commit and push to activate the pipeline."

FAQ

Discussion

Loading comments...

#!/bin/bash # GitHub Actions CI setup for Python set -e mkdir -p .github/workflows cat > .github/workflows/ci.yml << 'WORKFLOW' name: CI on: push: branches: [main] pull_request: branches: [main] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.12' - run: pip install ruff - run: ruff check . - run: ruff format --check . typecheck: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.12' - run: pip install -r requirements.txt - run: pip install mypy - run: mypy src/ --ignore-missing-imports test: runs-on: ubuntu-latest strategy: fail-fast: false matrix: python-version: ['3.11', '3.12', '3.13'] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} cache: pip - run: pip install -r requirements.txt - run: pip install pytest pytest-cov - run: pytest --cov=src --cov-report=xml --cov-fail-under=80 tests/ - uses: actions/upload-artifact@v4 if: matrix.python-version == '3.12' with: name: coverage-report path: coverage.xml WORKFLOW echo "CI workflow created at .github/workflows/ci.yml" echo "Commit and push to activate the pipeline."