github-actions

GitHub Actions 工作流配置与排错

补充说明

GitHub Actions 用 .github/workflows/*.yml 描述流水线，事件触发后在 GitHub 托管的 Runner 或自托管 Runner 上执行 Job。它不是一个本地命令，调试常借助 gh 和 act。

常用示例

mkdir -p .github/workflows
gh workflow list
gh workflow run ci.yml
gh run list --limit 10
gh run watch
gh run view --log-failed
gh run rerun <run-id> --failed

最小工作流：

name: CI
on:
  push:
    branches: [main]
  pull_request:
permissions:
  contents: read
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: [22, 24]
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm test

易错点与排错

• 工作流必须放在 .github/workflows/ 根目录；子目录里的 YAML 不会被执行。
• on 在 YAML 1.1 里可能被解析成布尔值；用引号或保持标准写法，提交前本地校验。
• GITHUB_TOKEN 的默认权限随仓库设置变化；需要写操作时显式声明 permissions。
• fork 提交的 PR 默认拿不到 secrets；不要把部署密钥暴露给 pull_request。
• pull_request_target 会在目标仓库上下文运行，处理不可信代码时风险极高。
• 每个 job 是独立 Runner；文件和环境变量不会自动跨 job 传递，用 artifacts 或 outputs。
• 缓存 key 不含 lockfile 哈希会拿到过期依赖；cache 命中不代表依赖正确。
• matrix 默认 fail-fast 会取消其他组合；要收集全部结果时设 fail-fast: false。
• 第三方 action 用完整 commit SHA 固定比用 tag 更安全。
• 自托管 Runner 的权限、网络和清理策略要单独设计；不要把它当托管 Runner 用。

相关命令

• gh — GitHub CLI
• act — 本地运行工作流
• gitlab-ci — GitLab 的同类方案

读完自测

合上页面，先回答，再展开对照。

1. 把工作流 YAML 放在 .github/workflows/ 的子目录里会执行吗？
2. fork 提交的 PR 默认能拿到仓库 secrets 吗？
3. 前后两个 job 之间如何传递文件和环境变量？