# Python 项目的 GitHub Actions CI 模板

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

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

```yaml
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
- 失败时上传一些调试产物

## 如果你的项目更简单

你也可以先用更小版本：

```yaml
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 版本

把：

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

改成直接固定：

```yaml
with:
  python-version: '3.11'
```

### 2. 如果你用 Poetry

把安装部分改成：

```yaml
      - 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

可以把核心步骤改成：

```yaml
      - 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/`，也可以写明确一点：

```yaml
      - name: Test
        run: pytest tests/ -q
```

## 最推荐的落地方式

如果你现在就要用：

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

## 一个很实际的提醒

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

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

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