GitHub Actions 工作流编写指南

1. 基本概念

什么是工作流文件？

• 文件必须保存在仓库的 .github/workflows 目录中
• 文件格式为 YAML，后缀为 .yml 或 .yaml
• 一个仓库可以有多个工作流文件

YAML 语法基础

key: value          # 基本的键值对
parent:             # 缩进表示层级关系
  child: value
array:              # 列表使用 - 表示
  - item1
  - item2

2. 工作流文件结构

2.1 名称定义（name）

name: My Workflow   # 工作流的名称，会显示在 Actions 页面

2.2 触发条件（on）

on:
  push:                    # 推送时触发
    branches:
      - main              # 只在 main 分支触发
  pull_request:           # PR 时触发
    branches: 
      - main
  schedule:               # 定时触发
    - cron: '0 0 * * *'   # 每天零点触发

常用的 cron 表达式：

• * * * * * 分别代表：分钟(0-59) 小时(0-23) 日期(1-31) 月份(1-12) 星期几(0-6)
• 0 0 * * * = 每天午夜
• 0 */4 * * * = 每4小时
• 0 9 * * 1-5 = 工作日早上9点

2.3 工作定义（jobs）

jobs:
  build:                  # 工作ID
    runs-on: ubuntu-latest    # 运行环境
    
    steps:                # 步骤定义
    - name: Step 1        # 步骤名称
      uses: actions/checkout@v2    # 使用现成的 action
      
    - name: Step 2
      run: echo "Hello"   # 运行命令

2.4 常用环境变量

env:
  GLOBAL_VAR: value      # 全局环境变量

jobs:
  job1:
    env:
      JOB_VAR: value     # 作业级环境变量
    steps:
      - env:
          STEP_VAR: value  # 步骤级环境变量

3. 实用示例

3.1 自动提交代码

name: Auto Commit

on:
  push:
    branches: [ main ]

jobs:
  commit:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Commit files
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add .
        git commit -m "Auto commit" || echo "No changes to commit"
        git push

3.2 自动构建和部署

name: Build and Deploy

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '14'
        
    - name: Install Dependencies
      run: npm install
      
    - name: Build
      run: npm run build

4. 常用 Actions

4.1 检出代码

- uses: actions/checkout@v2

4.2 设置环境

- uses: actions/setup-node@v2
  with:
    node-version: '14'

- uses: actions/setup-python@v2
  with:
    python-version: '3.8'

4.3 缓存依赖

- uses: actions/cache@v2
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

5. 最佳实践

5.1 使用密钥

steps:
  - name: Use Secret
    env:
      SUPER_SECRET: ${{ secrets.SUPER_SECRET }}
    run: echo "Using secret"

5.2 条件执行

steps:
  - name: Conditional Step
    if: github.event_name == 'push'
    run: echo "This only runs on push"

5.3 错误处理

steps:
  - name: Step that may fail
    continue-on-error: true
    run: echo "This step can fail safely"

6. 调试技巧

6.1 启用调试日志

在仓库的 Settings > Actions > Runner groups 中设置：

• ACTIONS_RUNNER_DEBUG=true
• ACTIONS_STEP_DEBUG=true

6.2 本地测试

可以使用 act 工具在本地测试 GitHub Actions：

# 安装 act
brew install act

# 运行工作流
act push