Python 项目的 GitHub Actions CI 模板¶

下面这份配置适合大多数常规 Python 项目直接作为起点使用：

文件路径建议：.github/workflows/ci.yml

name: Python CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
          if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
          if [ -f pyproject.toml ]; then pip install -e .; fi
          pip install pytest

      - name: Lint
        run: |
          if python -m pip show ruff >/dev/null 2>&1; then
            ruff check .
          else
            echo "ruff not installed, skip lint"
          fi

      - name: Test
        run: pytest -q

      - name: Upload test artifacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: pytest-debug-${{ matrix.python-version }}
          path: |
            .pytest_cache
            .coverage
          if-no-files-found: ignore
          retention-days: 7

这份模板适合什么项目¶

适合：
- 使用 requirements.txt 管理依赖的 Python 项目
- 使用 pyproject.toml 的现代 Python 项目
- 使用 pytest 作为测试框架的项目
- 想先把 CI 跑起来，再逐步增强的项目

这份模板做了什么¶

push 到 main / develop 时触发
提交 PR 到 main 时触发
支持手动触发
使用 Python 3.10 / 3.11 / 3.12 做矩阵测试
自动缓存 pip 依赖
安装基础依赖并运行 pytest
如果装了 ruff，就顺手做 lint
失败时上传一些调试产物

如果你的项目更简单¶

你也可以先用更小版本：

name: Python CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install pytest

      - name: Run tests
        run: pytest

常见按需调整¶

1. 只保留一个 Python 版本¶

把：

strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]

改成直接固定：

with:
  python-version: '3.11'

2. 如果你用 Poetry¶

把安装部分改成：

      - name: Install Poetry
        run: pip install poetry

      - name: Install dependencies
        run: poetry install --no-interaction --no-root

      - name: Test
        run: poetry run pytest -q

3. 如果你用 Ruff + Pytest + Coverage¶

可以把核心步骤改成：

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
          pip install ruff pytest pytest-cov

      - name: Lint
        run: ruff check .

      - name: Test
        run: pytest --cov=. --cov-report=xml

      - name: Upload coverage report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage.xml
          if-no-files-found: ignore

4. 如果测试目录不是默认结构¶

比如你的测试在 tests/，也可以写明确一点：

      - name: Test
        run: pytest tests/ -q

最推荐的落地方式¶

如果你现在就要用：

先把上面的“更小版本”放进 .github/workflows/ci.yml
确保本地先能跑通：pytest
push 到 GitHub
到 Actions 页面看日志
跑通后再加矩阵、lint、coverage

一个很实际的提醒¶

Python 项目 CI 最容易失败的 4 个点：

依赖文件不完整
本地能跑，CI 不能跑，通常是漏装依赖
Python 版本和本地不一致
测试里依赖环境变量、数据库或外部服务，但 workflow 没准备这些条件

所以最稳妥的起步方式是：
- 先单版本
- 先 pytest
- 先不接数据库/Redis/外部 API
- 跑通后再逐步加复杂能力