GitHub Actions CI/CD 完全指南 2026：自动化构建 + 测试 + 部署实战

1
name: CI/CD Pipeline        # Workflow 名称（显示在 Actions 标签页）
2

3
# 触发条件
4
on:
5
  push:
6
    branches: [main, develop]
7
    paths-ignore:            # 这些文件变更不触发
8
      - "**.md"
9
      - ".gitignore"
10
  pull_request:
11
    branches: [main]
12
  schedule:
13
    - cron: "0 2 * * *"    # 每天凌晨2点定时运行
14
  workflow_dispatch:         # 允许手动触发（Actions 页面有按钮）
15
    inputs:
16
      environment:
17
        description: "部署环境"
18
        required: true
19
        default: "staging"
20
        type: choice
21
        options: [staging, production]
22

23
# 环境变量（所有 job 共享）
24
env:
25
  REGISTRY: ghcr.io
26
  IMAGE_NAME: ${{ github.repository }}   # 仓库名，如 owner/repo
27

28
jobs:
29
  # ── Job 1：代码检查 ──────────────────────────────────────────
30
  lint:
31
    name: Lint & Format Check
32
    runs-on: ubuntu-24.04    # Runner 类型
33
    steps:
34
      - name: Checkout code
35
        uses: actions/checkout@v4
36

37
      - name: Set up Python
38
        uses: actions/setup-python@v5
39
        with:
40
          python-version: "3.12"
41
          cache: "pip"        # 自动缓存 pip 依赖
42

43
      - name: Install dependencies
44
        run: pip install ruff mypy
45

46
      - name: Run Ruff linter
47
        run: ruff check .
48

49
      - name: Run mypy type check
50
        run: mypy src/
51

52
  # ── Job 2：测试（依赖 lint 通过）────────────────────────────
53
  test:
54
    name: Run Tests
55
    runs-on: ubuntu-24.04
56
    needs: [lint]             # 等 lint job 成功后才运行
57
    services:
58
      # 启动附加服务容器（集成测试使用）
59
      postgres:
60
        image: postgres:16
61
        env:
62
          POSTGRES_DB: testdb
63
          POSTGRES_USER: testuser
64
          POSTGRES_PASSWORD: testpass
65
        ports:
66
          - 5432:5432
67
        options: >-
68
          --health-cmd pg_isready
69
          --health-interval 10s
70
          --health-timeout 5s
71
          --health-retries 5
72
      redis:
73
        image: redis:7-alpine
74
        ports:
75
          - 6379:6379
76
    env:
77
      DATABASE_URL: postgresql://testuser:testpass@localhost:5432/testdb
78
      REDIS_URL: redis://localhost:6379
79
    steps:
80
      - uses: actions/checkout@v4
81
      - uses: actions/setup-python@v5
82
        with:
83
          python-version: "3.12"
84
          cache: "pip"
85
      - run: pip install -r requirements.txt -r requirements-dev.txt
86
      - name: Run pytest with coverage
87
        run: |
88
          pytest tests/ \
89
            --cov=src \
90
            --cov-report=xml \
91
            --cov-report=term-missing \
92
            --junitxml=test-results.xml \
93
            -v
94
      - name: Upload coverage to Codecov
95
        uses: codecov/codecov-action@v4
96
        with:
97
          files: coverage.xml
98
          token: ${{ secrets.CODECOV_TOKEN }}
99

100
  # ── Job 3：多版本矩阵测试 ────────────────────────────────────
101
  test-matrix:
102
    name: Test Python ${{ matrix.python-version }}
103
    runs-on: ${{ matrix.os }}
104
    strategy:
105
      fail-fast: false        # 某个矩阵失败不停止其他
106
      matrix:
107
        os: [ubuntu-24.04, macos-14]
108
        python-version: ["3.11", "3.12"]
109
        exclude:
110
          - os: macos-14
111
            python-version: "3.11"   # 排除特定组合
112
    steps:
113
      - uses: actions/checkout@v4
114
      - uses: actions/setup-python@v5
115
        with:
116
          python-version: ${{ matrix.python-version }}
117
      - run: pip install -e ".[dev]"
118
      - run: pytest tests/ -x

1
name: Build & Push Docker Image
2

3
on:
4
  push:
5
    branches: [main]
6
    tags: ["v*.*.*"]          # 发布 tag 时触发
7

8
# 使用 OIDC 无密钥认证（推荐）
9
permissions:
10
  contents: read
11
  packages: write             # 允许推送到 GHCR
12
  id-token: write             # OIDC token
13

14
jobs:
15
  docker:
16
    name: Build & Push
17
    runs-on: ubuntu-24.04
18
    steps:
19
      - uses: actions/checkout@v4
20

21
      # 设置 QEMU（多平台构建需要）
22
      - name: Set up QEMU
23
        uses: docker/setup-qemu-action@v3
24

25
      # 设置 Docker Buildx
26
      - name: Set up Docker Buildx
27
        uses: docker/setup-buildx-action@v3
28

29
      # 登录 GitHub Container Registry（用 GITHUB_TOKEN，无需配置 Secret）
30
      - name: Log in to GHCR
31
        uses: docker/login-action@v3
32
        with:
33
          registry: ghcr.io
34
          username: ${{ github.actor }}
35
          password: ${{ secrets.GITHUB_TOKEN }}
36

37
      # 同时登录 Docker Hub（可选）
38
      - name: Log in to Docker Hub
39
        uses: docker/login-action@v3
40
        with:
41
          username: ${{ secrets.DOCKERHUB_USERNAME }}
42
          password: ${{ secrets.DOCKERHUB_TOKEN }}
43

44
      # 提取元数据（生成 tag 和 label）
45
      - name: Extract Docker metadata
46
        id: meta
47
        uses: docker/metadata-action@v5
48
        with:
49
          images: |
50
            ghcr.io/${{ github.repository }}
51
            ${{ secrets.DOCKERHUB_USERNAME }}/myapp
52
          tags: |
53
            type=ref,event=branch
54
            type=ref,event=pr
55
            type=semver,pattern={{version}}         # v1.2.3 → 1.2.3
56
            type=semver,pattern={{major}}.{{minor}} # v1.2.3 → 1.2
57
            type=sha,prefix=sha-                    # git commit sha
58
            type=raw,value=latest,enable={{is_default_branch}}
59

60
      # 构建并推送（多平台：amd64 + arm64）
61
      - name: Build and push
62
        uses: docker/build-push-action@v6
63
        with:
64
          context: .
65
          platforms: linux/amd64,linux/arm64
66
          push: ${{ github.event_name != 'pull_request' }}
67
          tags: ${{ steps.meta.outputs.tags }}
68
          labels: ${{ steps.meta.outputs.labels }}
69
          cache-from: type=gha          # 使用 GitHub Actions 缓存层
70
          cache-to: type=gha,mode=max   # 最大化缓存
71
          build-args: |
72
            BUILD_DATE=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
73
            GIT_SHA=${{ github.sha }}

1
name: Multi-Environment Deploy
2

3
on:
4
  push:
5
    branches: [main, staging]
6

7
jobs:
8
  deploy:
9
    runs-on: ubuntu-24.04
10
    # 根据分支选择 Environment（不同 Environment 有不同 Secrets）
11
    environment:
12
      name: ${{ github.ref_name == 'main' && 'production' || 'staging' }}
13
    steps:
14
      - uses: actions/checkout@v4
15

16
      - name: Deploy
17
        env:
18
          # 引用当前 Environment 的 Secrets
19
          DB_URL: ${{ secrets.DATABASE_URL }}
20
          API_KEY: ${{ secrets.API_KEY }}
21
        run: |
22
          echo "Deploying to ${{ vars.ENVIRONMENT_NAME }}"
23
          # vars 是非敏感的配置变量（公开可见），secrets 是加密的
24
          ./scripts/deploy.sh \
25
            --env ${{ vars.ENV_NAME }} \
26
            --version ${{ github.sha }}
27

28
  # production 环境需要手动审批（在 Environment 设置中配置 Required reviewers）
29
  notify:
30
    runs-on: ubuntu-24.04
31
    needs: deploy
32
    if: always()     # 无论成功失败都发通知
33
    steps:
34
      - name: Notify Telegram
35
        uses: appleboy/telegram-action@master
36
        with:
37
          to: ${{ secrets.TELEGRAM_CHAT_ID }}
38
          token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
39
          message: |
40
            ${{ job.status == 'success' && '✅' || '❌' }} 部署完成
41
            仓库: ${{ github.repository }}
42
            分支: ${{ github.ref_name }}
43
            提交: ${{ github.sha }}
44
            状态: ${{ needs.deploy.result }}

1
name: "Notify Deployment"
2
description: "发送部署结果通知"
3
inputs:
4
  status:
5
    description: "部署状态 (success/failure)"
6
    required: true
7
  environment:
8
    description: "部署环境"
9
    required: true
10
  telegram-token:
11
    description: "Telegram Bot Token"
12
    required: true
13
  telegram-chat-id:
14
    description: "Telegram Chat ID"
15
    required: true
16
outputs:
17
  message-id:
18
    description: "发送的消息 ID"
19
    value: ${{ steps.send.outputs.message-id }}
20

21
runs:
22
  using: "composite"
23
  steps:
24
    - name: Send Telegram notification
25
      id: send
26
      shell: bash
27
      env:
28
        STATUS: ${{ inputs.status }}
29
        ENV: ${{ inputs.environment }}
30
        TOKEN: ${{ inputs.telegram-token }}
31
        CHAT_ID: ${{ inputs.telegram-chat-id }}
32
      run: |
33
        EMOJI=$([[ "$STATUS" == "success" ]] && echo "✅" || echo "❌")
34
        MESSAGE="${EMOJI} *部署${STATUS}*%0A环境: ${ENV}%0A时间: $(date '+%Y-%m-%d %H:%M')"
35

36
        RESPONSE=$(curl -s -X POST \
37
          "https://api.telegram.org/bot${TOKEN}/sendMessage" \
38
          -d "chat_id=${CHAT_ID}&text=${MESSAGE}&parse_mode=Markdown")
39

40
        MESSAGE_ID=$(echo $RESPONSE | jq -r '.result.message_id')
41
        echo "message-id=$MESSAGE_ID" >> $GITHUB_OUTPUT