GitHub Actions 的 YAML 配置文件参数解析

GitHub Actions 的 YAML 配置文件进行一次全面、深入的解析。这个文件通常位于 .github/workflows/ 目录下，例如 .github/workflows/ci.yml。

核心概念

一个 Workflow（工作流程）文件由一系列键值对组成，定义了自动化过程的各个组成部分。最高级别的键如下所示：

1. `name` - 工作流程名称

作用：为整个工作流程提供一个易读的名称。这个名字会显示在 GitHub 仓库的 Actions 标签页中。

示例：

yaml
name: CI/CD Pipeline for Node.js Application

注意：

可选，但强烈建议设置，便于识别。
如果省略，则使用工作流文件的名称。

2. `on` - 触发事件

作用：定义什么事件会触发工作流程的运行。这是工作流的“开关”。

常见值：

push: 向分支推送代码时触发。
pull_request: 创建或更新 Pull Request 时触发。
schedule: 按计划时间触发（使用 cron 语法）。
workflow_dispatch: 允许在 GitHub 页面上手动触发。
release: 创建或发布 release 时触发。

示例：

yaml
on:
  # 推送到 main 或 develop 分支时触发
  push:
    branches: [ main, develop ]
  # 针对 main 分支的 PR 时触发
  pull_request:
    branches: [ main ]
  # 每天 UTC 时间 凌晨 2:30 运行一次 (注意时区！)
  schedule:
    - cron: '30 2 * * *'
  # 启用手动触发
  workflow_dispatch:

注意与扩展：

路径过滤：可以只在对特定路径的文件更改时才触发。

yaml
on:
  push:
    branches: [ main ]
    paths: [ 'src/**', 'package.json' ] # 只有 src 目录或 package.json 变化时才触发
    paths-ignore: [ 'docs/**' ] # 忽略 docs 目录的更改

活动类型：对于 pull_request 或 issue_comment 等事件，可以指定具体活动类型。

yaml
on:
  issues:
    types: [opened, labeled] # 仅当 issue 被创建或打标签时触发

3. `jobs` - 任务集合

作用：工作流程的核心，由一个或多个任务（job）组成。默认情况下，jobs 并行运行。

3.1. `jobs.<job_id>` - 任务ID

作用：定义一个唯一的任务。job_id 是你自定义的键，必须是字母数字且以字母或_开头。

示例：

yaml
jobs:
  build: # <job_id> 是 'build'
    ...
  test:
    ...
  deploy:
    ...

3.2. `jobs.<job_id>.runs-on` - 运行环境

作用：指定任务运行在哪种运行器上。

示例：

yaml
jobs:
  build:
    runs-on: ubuntu-latest # 使用 GitHub 托管的 Ubuntu 最新版虚拟机
  test-windows:
    runs-on: windows-latest # 使用 Windows 虚拟机
  test-matrix: # 使用策略矩阵，在不同系统和Node版本下运行
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [14, 16, 18]

注意：

对于公共仓库，GitHub 托管的运行器是免费的，但有使用限制（分钟数和硬件配置）。
你可以使用自托管运行器（self-hosted runners）来获得更多控制权或特定环境（如 GPU）。
```
yaml
runs-on: [self-hosted, linux, x64, gpu] # 使用带有GPU的自托管Linux机器
```

3.3. `jobs.<job_id>.needs` - 依赖关系

作用：定义任务之间的依赖关系，确保任务按顺序运行而不是并行运行。

示例：

yaml
jobs:
  lint:
    ...
  build:
    needs: lint # build 任务需要等待 lint 任务成功完成后才能运行
  test:
    needs: build # test 任务需要等待 build 任务成功完成
  deploy:
    needs: [test, build] # deploy 任务需要等待 test 和 build 都成功

注意：如果 lint 任务失败，build 和 test 将不会运行，整个工作流会失败。

3.4. `jobs.<job_id>.if` - 条件判断

作用：根据条件决定是否运行该任务。

示例：

yaml
jobs:
  deploy-prod:
    runs-on: ubuntu-latest
    # 只有推送到 main 分支时才运行部署任务
    if: github.ref == 'refs/heads/main'
    steps:
      ...

3.5. `jobs.<job_id>.env` - 环境变量

作用：为任务中的所有 step 定义默认环境变量。

示例：

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
      CI: true
    steps:
      - run: echo $NODE_ENV # 会输出 'production'

3.6. `jobs.<job_id>.strategy.matrix` - 策略矩阵

作用：极其强大的功能。允许你基于多个变量（如操作系统、语言版本）自动创建多个任务运行组合。

示例：

yaml
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
        node-version: [16, 18, 20]
        # 会生成 2 (os) x 3 (node) = 6 个不同的任务组合
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

注意与扩展：

排除组合：可以使用 exclude 关键字移除某些组合。
包含组合：可以使用 include 关键字添加额外的特定组合。
失败处理：strategy.fail-fast 默认为 true，即矩阵中任何一个任务失败，所有正在运行的任务都会被取消。设为 false 可以让其他任务继续完成。

4. `jobs.<job_id>.steps` - 步骤序列

作用：定义一个任务中按顺序执行的一系列步骤（step）。

4.1. `steps[*].id` - 步骤标识

作用：为步骤提供一个唯一标识符，可用于后续步骤的上下文引用。

示例：

yaml
steps:
  - id: get-version
    run: echo "::set-output name=version::v1.0.0"
  - name: Use the version
    run: echo "The version is ${{ steps.get-version.outputs.version }}"

4.2. `steps[*].name` - 步骤名称

作用：步骤的可读描述，会显示在日志中。

示例：

yaml
steps:
  - name: Install dependencies
    run: npm ci

4.3. `steps[*].uses` - 使用 Action

作用：使用可重用的 Action。这是复用代码的核心。

示例：

yaml
steps:
  - name: Checkout code
    uses: actions/checkout@v4 # 使用官方 checkout action

  - name: Setup Node.js
    uses: actions/setup-node@v3
    with: # 向 Action 传递参数
      node-version: '18'
      cache: 'npm'

注意：

锁定版本：务必使用特定版本（如 @v3），不要使用 @main 或 @master，以免未来的变更破坏你的工作流。
公共市场：可以在 GitHub Marketplace 找到无数可用的 Action。

4.4. `steps[*].run` - 运行命令

作用：在运行器上执行 shell 命令。

示例：

yaml
steps:
  - name: Run tests and generate coverage
    run: |
      npm test
      npm run coverage:ci
    # 可选：指定shell
    shell: bash

注意：

默认 shell 取决于操作系统（Linux/macOS 是 bash，Windows 是 pwsh）。
可以使用 | 来编写多行命令。

4.5. `steps[*].with` - 输入参数

作用：提供给 uses 指令所调用的 Action 的输入参数映射。

示例：

yaml
- uses: actions/upload-artifact@v3
  with:
    name: my-artifact
    path: build/
    retention-days: 5

4.6. `steps[*].env` - 步骤环境变量

作用：设置仅用于该步骤的环境变量，会覆盖 job 级别的 env。

示例：

yaml
steps:
  - name: Build with a custom env
    run: npm run build:staging
    env:
      NODE_ENV: staging
      API_URL: ${{ secrets.STAGING_API_URL }}

4.7. `steps[*].if` - 步骤条件

作用：根据条件决定是否运行该步骤。

示例：

yaml
steps:
  - name: Build for production
    if: github.ref == 'refs/heads/main'
    run: npm run build:prod

  - name: Build for staging
    if: github.ref != 'refs/heads/main'
    run: npm run build:staging

5. `env` - 全局环境变量

作用：定义整个工作流程中所有 job 和 step 都可用的默认环境变量。

示例：

yaml
env:
  NODE_ENV: ci
  LOG_LEVEL: debug

jobs:
  ...

6. `defaults` - 默认设置

作用：为工作流中所有 job 的所有 step 提供默认设置。

示例：

yaml
defaults:
  run:
    shell: bash # 为所有 `run` step 设置默认的 shell
    working-directory: ./src # 为所有 `run` step 设置默认的工作目录

完整示例

yaml
name: Node.js CI

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

env:
  CI: true

jobs:
  test:
    name: Test on Node ${{ matrix.node-version }} and ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node-version: [16.x, 18.x, 20.x]

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

    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'

    - name: Install dependencies
      run: npm ci

    - name: Run tests
      run: npm test

    - name: Upload coverage reports
      if: success()
      uses: actions/upload-artifact@v3
      with:
        name: coverage-report-${{ matrix.os }}-node-${{ matrix.node-version }}
        path: coverage/

  deploy:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: test # 只有在 test job 成功后才能运行
    if: github.ref == 'refs/heads/main' # 只有 main 分支才部署

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

    - name: Deploy using SSH
      uses: appleboy/ssh-action@master
      with:
        host: ${{ secrets.PRODUCTION_HOST }}
        username: ${{ secrets.PRODUCTION_USER }}
        key: ${{ secrets.SSH_PRIVATE_KEY }}
        script: |
          cd /app
          git pull
          npm ci --production
          pm2 restart my-app

通过掌握这些参数，就可以构建出极其灵活且高效的自动化工作流，满足从简单的 CI 测试到复杂的 CD 部署等各种场景需求。

目录

核心概念

1. name - 工作流程名称

2. on - 触发事件

3. jobs - 任务集合

3.1. jobs.<job_id> - 任务ID

3.2. jobs.<job_id>.runs-on - 运行环境

3.3. jobs.<job_id>.needs - 依赖关系

3.4. jobs.<job_id>.if - 条件判断

3.5. jobs.<job_id>.env - 环境变量

3.6. jobs.<job_id>.strategy.matrix - 策略矩阵

4. jobs.<job_id>.steps - 步骤序列

4.1. steps[*].id - 步骤标识

4.2. steps[*].name - 步骤名称

4.3. steps[*].uses - 使用 Action

4.4. steps[*].run - 运行命令

4.5. steps[*].with - 输入参数

4.6. steps[*].env - 步骤环境变量

4.7. steps[*].if - 步骤条件

5. env - 全局环境变量

6. defaults - 默认设置