writing-github-actions

编写 GitHub Actions

使用基于 YAML 的配置和原生 GitHub 集成，为 CI/CD 流水线、自动化测试、部署和仓库自动化创建 GitHub Actions 工作流。

用途

GitHub Actions 是 GitHub 仓库的原生 CI/CD 平台。本技能涵盖 GitHub Actions 特有的工作流语法、触发器、作业编排、可复用模式、优化技巧和安全实践。

核心关注点：

• 工作流 YAML 语法和结构
• 可复用工作流和复合操作
• 矩阵构建和并行执行
• 缓存和优化策略
• 密钥管理和 OIDC 身份验证
• 并发控制和构件管理

不涵盖：

• CI/CD 流水线设计策略 → 请参阅 building-ci-pipelines
• GitOps 部署模式 → 请参阅 gitops-workflows
• 基础设施即代码 → 请参阅 infrastructure-as-code
• 测试框架 → 请参阅 testing-strategies

何时使用此技能

在以下情况下触发此技能：

• 为 GitHub 仓库创建 CI/CD 工作流
• 通过 GitHub Actions 自动化测试、构建和部署
• 在多个仓库之间设置可复用工作流
• 使用缓存和并行化优化工作流性能
• 为 GitHub Actions 实施安全最佳实践
• 排查 GitHub Actions YAML 语法或行为问题

工作流基础知识

基本工作流结构

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

关键组件：

• name：工作流显示名称
• on：触发事件（push、pull_request、schedule、workflow_dispatch）
• jobs：作业定义（默认并行运行）
• runs-on：运行器类型（ubuntu-latest、windows-latest、macos-latest）
• steps：按顺序执行的操作（使用操作或运行命令）

常见触发器

# Code events
on:
  push:
    branches: [main, develop]
    paths: ['src/**']
  pull_request:
    types: [opened, synchronize, reopened]

# Manual trigger
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, staging, production]

# Scheduled
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM UTC

完整的触发器参考，请参阅 references/triggers-events.md。

决策框架

可复用工作流与复合操作

适用可复用工作流的情况：

• 在多个仓库之间统一整个 CI/CD 作业
• 需要通过输入/输出完整替换作业
• 希望默认继承密钥
• 使用作业级配置编排多个步骤

适用复合操作的情况：

• 将包含 5-20 个步骤的序列打包以供复用
• 需要在作业内进行步骤级抽象
• 希望通过 Marketplace 或私有仓库分发
• 需要直接访问本地文件，而无需使用构件

特性	可复用工作流	复合操作
范围	完整作业	步骤序列
触发方式	workflow_call	步骤中的 uses:
密钥	默认继承	必须显式传递
文件共享	需要构件	使用同一运行器/工作区

有关详细模式，请参阅 references/reusable-workflows.md 和 references/composite-actions.md。

缓存策略

使用内置设置操作缓存（推荐）：

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # or 'yarn', 'pnpm'

适用于：Node.js、Python（pip）、Java（maven/gradle）、.NET、Go

以下情况使用手动缓存：

• 需要自定义缓存键
• 缓存构建输出或非标准路径
• 实施多层缓存策略

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

有关优化技巧，请参阅 references/caching-strategies.md。

自托管运行器与 GitHub 托管运行器

适用 GitHub 托管运行器的情况：

• 标准构建环境已足够
• 不需要访问私有网络
• 未超出预算或免费套餐限制

适用自托管运行器的情况：

• 需要特定硬件（GPU、ARM、大内存）
• 需要访问私有网络/VPN
• 使用量大（优化成本）
• 必须预装自定义软件

常见模式

带依赖关系的多作业工作流

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v5
        with:
          name: dist
      - run: npm test

  deploy:
    needs: [build, test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v5
      - run: ./deploy.sh

关键要素：

• needs: 创建作业依赖关系（按顺序执行）
• 构件在作业之间传递数据
• if: 启用条件执行
• environment: 启用保护规则和环境密钥

矩阵构建

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

结果：9 个作业（3 种操作系统 × 3 个 Node 版本）

有关高级矩阵模式，请参阅 examples/matrix-build.yml。

并发控制

# Cancel in-progress runs on new push
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Single deployment per environment
jobs:
  deploy:
    concurrency:
      group: production-deployment
      cancel-in-progress: false
    steps: [...]

可复用工作流

定义可复用工作流

文件：.github/workflows/reusable-build.yml

name: Reusable Build
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
    secrets:
      NPM_TOKEN:
        required: false
    outputs:
      artifact-name:
        value: ${{ jobs.build.outputs.artifact }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact: build-output
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

调用可复用工作流

jobs:
  build:
    uses: ./.github/workflows/reusable-build.yml
    with:
      node-version: '20'
    secrets: inherit  # Same org only

完整的可复用工作流指南请参阅 references/reusable-workflows.md。

复合操作

定义复合操作

文件：.github/actions/setup-project/action.yml

name: 'Setup Project'
description: 'Install dependencies and setup environment'

inputs:
  node-version:
    description: 'Node.js version'
    default: '20'

outputs:
  cache-hit:
    value: ${{ steps.cache.outputs.cache-hit }}

runs:
  using: "composite"
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: 'npm'

    - id: cache
      uses: actions/cache@v4
      with:
        path: node_modules
        key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json') }}

    - if: steps.cache.outputs.cache-hit != 'true'
      shell: bash
      run: npm ci

关键要求：

• runs.using: "composite" 用于标记操作类型
• 所有 run 步骤都必须指定 shell:
• 通过 ${{ inputs.name }} 访问输入

使用复合操作

steps:
  - uses: actions/checkout@v5
  - uses: ./.github/actions/setup-project
    with:
      node-version: '20'
  - run: npm run build

复合操作模式的详细说明请参阅 references/composite-actions.md。

安全最佳实践

密钥管理

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Uses environment secrets
    steps:
      - env:
          API_KEY: ${{ secrets.API_KEY }}
        run: ./deploy.sh

OIDC 身份验证（无需长期凭证）

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: us-east-1
      - run: aws s3 sync ./dist s3://my-bucket

最小权限

# Workflow-level
permissions:
  contents: read
  pull-requests: write

# Job-level
jobs:
  deploy:
    permissions:
      contents: write
      deployments: write
    steps: [...]

固定操作版本

# Pin to commit SHA (not tags)
- uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608  # v5.0.0

启用 Dependabot：

文件：.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

全面的安全指南请参阅 references/security-practices.md。

优化技巧

使用设置操作中内置的缓存（cache: 'npm'），并行运行相互独立的作业，使用 if: 添加条件执行，并尽量减少检出深度（fetch-depth: 1）。

详细的优化策略请参阅 references/caching-strategies.md。

上下文变量

常用上下文：github.*、secrets.*、inputs.*、matrix.*、runner.*

- run: echo "Branch: ${{ github.ref }}, Event: ${{ github.event_name }}"

完整的语法参考请参阅 references/workflow-syntax.md。

渐进式呈现

详细参考资料

如需全面了解特定主题，请参阅：

• references/workflow-syntax.md - 完整的 YAML 语法参考
• references/reusable-workflows.md - 高级可复用工作流模式
• references/composite-actions.md - 复合操作深入解析
• references/caching-strategies.md - 优化和缓存技巧
• references/security-practices.md - 全面的安全指南
• references/triggers-events.md - 所有触发器类型和事件筛选器
• references/marketplace-actions.md - 推荐操作目录

工作示例

可直接使用的完整工作流模板：

• examples/basic-ci.yml - 简单的 CI 工作流
• examples/matrix-build.yml - 矩阵策略示例
• examples/reusable-deploy.yml - 可复用部署工作流
• examples/composite-setup/ - 复合操作模板
• examples/monorepo-workflow.yml - 带路径筛选器的单体仓库工作流
• examples/security-scan.yml - 安全扫描工作流

验证脚本

• scripts/validate-workflow.sh - 验证 YAML 语法

相关技能

• building-ci-pipelines - CI/CD 流水线设计策略
• gitops-workflows - GitOps 部署模式
• infrastructure-as-code - Terraform/Pulumi 集成
• testing-strategies - 测试框架和覆盖率
• security-hardening - SAST/DAST 工具
• git-workflows - 了解分支和 PR