github-actions

GitHub Actions 实战编写与调试

目标：快速编写正确的 GitHub Actions workflow，高效调试失败，理解平台行为边界。

实验仓库：st1page/gh-actions-lab（9 个场景的完整 workflow 示例）

1. 触发方式速查

触发	on: 写法	典型用途
Push	push: { branches: [main], paths: ["src/**"] }	CI
PR	pull_request: { branches: [main] }	代码审查
定时	schedule: [{ cron: "*/15 * * * *" }]	周期任务
手动	workflow_dispatch: { inputs: ... }	按需触发
API	repository_dispatch 或 gh workflow run	外部集成

paths filter 边界：只匹配 push 事件中实际变更的文件；如果 commit 没改 src/** 下的文件，即使 push 到 main 也不触发。workflow_dispatch 触发时 paths filter 不生效。

cron 延迟：GitHub 不保证 cron 准时触发，高峰期可延迟 5–30 分钟。Cron 只在 default branch 生效。

2. Job 依赖与条件执行

needs DAG

jobs:
  build: ...
  test-unit:
    needs: build        # build 完成后才跑
  test-integration:
    needs: build        # 与 test-unit 并行
  deploy:
    needs: [test-unit, test-integration]  # 两个都过才 deploy

needs 形成 DAG，同层无依赖的 job 自动并行。

if 条件

# commit message 包含 [deploy] 时才执行
- if: contains(github.event.head_commit.message, '[deploy]')

# 仅 PR 事件
- if: github.event_name == 'pull_request'

# 前置 job 失败也要跑（清理/汇报）
jobs:
  observer:
    needs: [job_a, job_b]
    if: always()    # 不管前置结果都跑

concurrency 控制

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true    # 新 run 自动取消旧 run

3. 重试策略

Step 级重试（nick-fields/retry）

- uses: nick-fields/retry@v3
  with:
    timeout_minutes: 2
    max_attempts: 3
    retry_wait_seconds: 5
    command: |
      # 可能偶发失败的命令
      curl -f https://example.com/api

Run 级重跑

# 全量重跑（所有 job 重新执行）
gh run rerun <run-id>

# 仅重跑失败的 job（已成功的跳过）
gh run rerun <run-id> --failed

run_attempt 递增：每次 rerun，github.run_attempt +1（首次为 1）。可用于区分首次运行和重跑：

- run: echo "Attempt ${{ github.run_attempt }}"

Artifact 名中带 attempt 可追踪每次运行的产物差异。

4. Secret & Variable 注入

设置

gh secret set API_KEY --body "xxx" -R owner/repo
gh variable set DEPLOY_TARGET --body "staging" -R owner/repo