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: - mainschedule:               # 定时触发- 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:                  # 工作IDruns-on: ubuntu-latest    # 运行环境steps:                # 步骤定义- name: Step 1        # 步骤名称uses: actions/checkout@v2    # 使用现成的 action- name: Step 2run: echo "Hello"   # 运行命令

2.4 常用环境变量

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

3. 实用示例

3.1 自动提交代码

name: Auto Commiton:push:branches: [ main ]jobs:commit:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- name: Commit filesrun: |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 Deployon:push:branches: [ main ]jobs:build:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v2- name: Setup Node.jsuses: actions/setup-node@v2with:node-version: '14'- name: Install Dependenciesrun: npm install- name: Buildrun: npm run build

4. 常用 Actions

4.1 检出代码

- uses: actions/checkout@v2

4.2 设置环境

- uses: actions/setup-node@v2with:node-version: '14'- uses: actions/setup-python@v2with:python-version: '3.8'

4.3 缓存依赖

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

5. 最佳实践

5.1 使用密钥

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

5.2 条件执行

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

5.3 错误处理

steps:- name: Step that may failcontinue-on-error: truerun: 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