GitHub Actions 完整指南：从入门到实践

什么是 GitHub Actions？#

GitHub Actions 是 GitHub 提供的强大 CI/CD 服务，让你可以直接在 GitHub 仓库中创建自动化工作流。无论是代码构建、测试、部署，还是其他任何可以自动化的任务，GitHub Actions 都能帮你轻松实现。

核心概念#

工作流 (Workflow)：一个可配置的自动化过程，由一个或多个作业组成
作业 (Job)：工作流中的一个执行单元，包含一系列步骤
步骤 (Step)：作业中的单个任务，可以运行命令或使用 Action
事件 (Event)：触发工作流运行的特定活动
运行器 (Runner)：执行工作流的服务器环境

基本语法和配置#

文件位置#

所有工作流文件都必须放在仓库的 .github/workflows/ 目录下，使用 .yml 或 .yaml 扩展名。

基本结构#

1
name: 工作流名称
2

3
# 触发条件
4
on:
5
  push:
6
    branches: [ main ]
7
  pull_request:
8
    branches: [ main ]
9

10
# 权限设置
11
permissions:
12
  contents: read
13

14
# 作业定义
15
jobs:
16
  job-name:
17
    runs-on: ubuntu-latest
18
    steps:
19
      - name: 步骤名称
20
        uses: actions/checkout@v4
21
      - name: 运行命令
22
        run: echo "Hello World"

触发器详解#

常用触发事件#

1
on:
2
  # 代码推送时触发
3
  push:
4
    branches: [ main, develop ]
5
    paths: [ 'src/**', 'package.json' ]  # 只有这些路径变化时才触发
6

7
  # 拉取请求时触发
8
  pull_request:
9
    branches: [ main ]
10
    types: [ opened, synchronize, reopened ]
11

12
  # 定时触发（使用 cron 语法）
13
  schedule:
14
    - cron: '0 2 * * 1-5'  # 工作日凌晨2点
15

16
  # 手动触发
17
  workflow_dispatch:
18
    inputs:
19
      environment:
20
        description: '部署环境'
21
        required: true
22
        default: 'staging'
23
        type: choice
24
        options: ['staging', 'production']
25
      version:
26
        description: '版本号'
27
        required: false
28
        type: string
29

30
  # Release 发布时触发
31
  release:
32
    types: [ published ]

手动触发的高级用法#

1
workflow_dispatch:
2
  inputs:
3
    deploy_target:
4
      description: '部署目标'
5
      required: true
6
      type: choice
7
      options: ['staging', 'production', 'development']
8
    skip_tests:
9
      description: '跳过测试'
10
      required: false
11
      type: boolean
12
      default: false
13
    custom_message:
14
      description: '自定义消息'
15
      required: false
16
      type: string
17
      default: 'Manual deployment'

并发控制#

防止同一分支上的工作流同时运行，避免资源冲突：

1
concurrency:
2
  group: ${{ github.workflow }}-${{ github.ref }}
3
  cancel-in-progress: true

权限管理#

为工作流设置最小权限原则：

1
permissions:
2
  contents: read          # 读取仓库内容
3
  issues: write          # 写入 Issues
4
  pull-requests: write   # 写入 PR
5
  actions: read          # 读取 Actions
6
  checks: write          # 写入检查状态

构建矩阵#

在多个环境下并行测试：

1
jobs:
2
  test:
3
    strategy:
4
      matrix:
5
        # 基础矩阵
6
        node-version: [18, 20, 22]
7
        os: [ubuntu-latest, windows-latest, macos-latest]
8

9
        # 排除特定组合
10
        exclude:
11
          - os: windows-latest
12
            node-version: 18
13

14
        # 包含特定组合
15
        include:
16
          - os: ubuntu-latest
17
            node-version: 16
18
            experimental: true
19

20
    runs-on: ${{ matrix.os }}
21
    continue-on-error: ${{ matrix.experimental == true }}
22

23
    steps:
24
      - uses: actions/checkout@v4
25
      - uses: actions/setup-node@v4
26
        with:
27
          node-version: ${{ matrix.node-version }}
28
      - run: npm ci
29
      - run: npm test

环境变量和 Secrets#

环境变量#

1
env:
2
  # 工作流级别的环境变量
3
  NODE_ENV: production
4
  APP_VERSION: v1.0.0
5

6
jobs:
7
  build:
8
    env:
9
      # 作业级别的环境变量
10
      BUILD_TARGET: web
11

12
    steps:
13
      - name: 构建应用
14
        run: npm run build
15
        env:
16
          # 步骤级别的环境变量
17
          GENERATE_SOURCEMAP: false
18
          REACT_APP_API_URL: ${{ secrets.API_URL }}

Secrets 使用#

在 GitHub 仓库设置中添加 Secrets，然后在工作流中引用：

1
steps:
2
  - name: 部署到云服务
3
    run: |
4
      echo "部署到生产环境..."
5
      ./deploy.sh
6
    env:
7
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
8
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
9
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
10
      API_KEY: ${{ secrets.API_KEY }}

实际项目示例#

Node.js 项目 CI/CD 完整流程#

1
name: Node.js CI/CD Pipeline
2

3
on:
4
  push:
5
    branches: [ main, develop ]
6
  pull_request:
7
    branches: [ main ]
8
  workflow_dispatch:
9
    inputs:
10
      deploy_env:
11
        description: '部署环境'
12
        required: true
13
        default: 'staging'
14
        type: choice
15
        options: ['staging', 'production']
16

17
concurrency:
18
  group: ${{ github.workflow }}-${{ github.ref }}
19
  cancel-in-progress: true
20

21
permissions:
22
  contents: read
23
  checks: write
24
  pull-requests: write
25

26
jobs:
27
  # 代码质量检查
28
  lint-and-type-check:
29
    runs-on: ubuntu-latest
30
    steps:
31
      - uses: actions/checkout@v4
32

33
      - uses: actions/setup-node@v4
34
        with:
35
          node-version: '20'
36
          cache: 'npm'
37

38
      - run: npm ci
39

40
      - name: 代码格式检查
41
        run: npm run lint
42

43
      - name: 类型检查
44
        run: npm run type-check
45

46
  # 单元测试
47
  test:
48
    runs-on: ubuntu-latest
49
    strategy:
50
      matrix:
51
        node-version: [18, 20, 22]
52
    steps:
53
      - uses: actions/checkout@v4
54

55
      - uses: actions/setup-node@v4
56
        with:
57
          node-version: ${{ matrix.node-version }}
58
          cache: 'npm'
59

60
      - run: npm ci
61

62
      - name: 运行测试
63
        run: npm test -- --coverage
64

65
      - name: 上传覆盖率报告
66
        uses: codecov/codecov-action@v3
67
        if: matrix.node-version == '20'
68
        with:
69
          token: ${{ secrets.CODECOV_TOKEN }}
70

71
  # 构建应用
72
  build:
73
    needs: [lint-and-type-check, test]
74
    runs-on: ubuntu-latest
75
    steps:
76
      - uses: actions/checkout@v4
77

78
      - uses: actions/setup-node@v4
79
        with:
80
          node-version: '20'
81
          cache: 'npm'
82

83
      - run: npm ci
84

85
      - name: 构建生产版本
86
        run: npm run build
87
        env:
88
          NODE_ENV: production
89

90
      - name: 上传构建产物
91
        uses: actions/upload-artifact@v4
92
        with:
93
          name: dist
94
          path: dist/
95
          retention-days: 30
96

97
  # 部署到 staging
98
  deploy-staging:
99
    if: github.ref == 'refs/heads/develop'
100
    needs: build
101
    runs-on: ubuntu-latest
102
    environment: staging
103
    steps:
104
      - name: 下载构建产物
105
        uses: actions/download-artifact@v4
106
        with:
107
          name: dist
108
          path: dist/
109

110
      - name: 部署到 Staging
111
        run: |
112
          echo "部署到 Staging 环境..."
113
          # 这里添加实际的部署脚本
114
        env:
115
          DEPLOY_KEY: ${{ secrets.STAGING_DEPLOY_KEY }}
116
          SERVER_HOST: ${{ secrets.STAGING_SERVER_HOST }}
117

118
  # 部署到 production
119
  deploy-production:
120
    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
121
    needs: build
122
    runs-on: ubuntu-latest
123
    environment: production
124
    steps:
125
      - name: 下载构建产物
126
        uses: actions/download-artifact@v4
127
        with:
128
          name: dist
129
          path: dist/
130

131
      - name: 部署到 Production
132
        run: |
133
          echo "部署到生产环境..."
134
          echo "部署环境: ${{ github.event.inputs.deploy_env || 'production' }}"
135
          # 这里添加实际的部署脚本
136
        env:
137
          DEPLOY_KEY: ${{ secrets.PROD_DEPLOY_KEY }}
138
          SERVER_HOST: ${{ secrets.PROD_SERVER_HOST }}

常用 Actions#

官方 Actions#

1
steps:
2
  # 检出代码
3
  - uses: actions/checkout@v4
4
    with:
5
      fetch-depth: 0  # 获取完整历史记录
6

7
  # 设置 Node.js 环境
8
  - uses: actions/setup-node@v4
9
    with:
10
      node-version: '20'
11
      cache: 'npm'
12
      registry-url: 'https://registry.npmjs.org'
13

14
  # 设置 Python 环境
15
  - uses: actions/setup-python@v4
16
    with:
17
      python-version: '3.11'
18
      cache: 'pip'
19

20
  # 缓存依赖
21
  - uses: actions/cache@v3
22
    with:
23
      path: ~/.npm
24
      key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
25

26
  # 上传/下载构建产物
27
  - uses: actions/upload-artifact@v4
28
    with:
29
      name: build-files
30
      path: dist/
31

32
  - uses: actions/download-artifact@v4
33
    with:
34
      name: build-files
35
      path: ./dist

第三方 Actions#

1
steps:
2
  # Docker 构建和推送
3
  - uses: docker/setup-buildx-action@v3
4
  - uses: docker/login-action@v3
5
    with:
6
      username: ${{ secrets.DOCKER_USERNAME }}
7
      password: ${{ secrets.DOCKER_PASSWORD }}
8

9
  - uses: docker/build-push-action@v5
10
    with:
11
      push: true
12
      tags: myapp:latest
13

14
  # Slack 通知
15
  - uses: 8398a7/action-slack@v3
16
    with:
17
      status: ${{ job.status }}
18
      channel: '#deployments'
19
    env:
20
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

最佳实践#

1. 工作流优化#

1
# 使用缓存加速构建
2
- uses: actions/cache@v3
3
  with:
4
    path: ~/.npm
5
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
6
    restore-keys: |
7
      ${{ runner.os }}-npm-
8

9
# 并行执行作业
10
jobs:
11
  test:
12
    # 测试作业
13
  lint:
14
    # 代码检查作业
15
  build:
16
    needs: [test, lint]  # 依赖前面的作业

2. 安全实践#

1
# 最小权限原则
2
permissions:
3
  contents: read
4

5
# 使用 Secrets 存储敏感信息
6
env:
7
  API_KEY: ${{ secrets.API_KEY }}
8

9
# 环境保护规则
10
environment: production  # 需要手动审批

3. 错误处理#

1
steps:
2
  - name: 可能失败的步骤
3
    run: npm test
4
    continue-on-error: true
5

6
  - name: 条件执行
7
    if: failure()  # 只有前面步骤失败时才执行
8
    run: echo "Tests failed, sending notification..."

4. 调试和监控#

1
steps:
2
  - name: 调试信息
3
    run: |
4
      echo "Runner OS: ${{ runner.os }}"
5
      echo "GitHub Event: ${{ github.event_name }}"
6
      echo "Branch: ${{ github.ref }}"
7

8
  - name: 设置输出
9
    id: build-info
10
    run: echo "version=$(npm version --json | jq -r .version)" >> $GITHUB_OUTPUT
11

12
  - name: 使用输出
13
    run: echo "Built version ${{ steps.build-info.outputs.version }}"

总结#

GitHub Actions 提供了强大而灵活的 CI/CD 解决方案。通过合理使用触发器、构建矩阵、环境变量和 Secrets，你可以创建高效、安全、可维护的自动化工作流。

关键要点：

合理设计工作流结构 - 将相关任务分组到不同作业中
使用构建矩阵 - 在多环境下并行测试
管理好 Secrets - 保护敏感信息安全
优化性能 - 使用缓存和并行执行
遵循最佳实践 - 最小权限、错误处理、监控调试

通过这些实践，你可以构建出稳定可靠的 DevOps 流水线。