⚡

编写GitHubActionsSkill writing-github-actions

本技能专注于教授如何使用GitHub Actions创建和管理CI/CD工作流，用于自动化测试、构建、部署和仓库任务。涵盖YAML语法、可重用工作流、复合动作、矩阵构建、缓存策略及安全性最佳实践。关键词：GitHub Actions, CI/CD, 自动化, YAML, DevOps, 工作流, 缓存, 安全性。

CI/CD 0 次安装 0 次浏览 更新于 3/23/2026

name: 编写github-actions description: 使用正确的语法、可重用工作流、复合动作、矩阵构建、缓存和安全性最佳实践来编写GitHub Actions工作流。适用于为GitHub托管的项目创建CI/CD工作流或自动化GitHub仓库任务。

编写 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: 顺序操作（使用动作或运行命令）

常见触发器

# 代码事件
on:
  push:
    branches: [main, develop]
    paths: ['src/**']
  pull_request:
    types: [opened, synchronize, reopened]

# 手动触发
on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [dev, staging, production]

# 计划任务
on:
  schedule:
    - cron: '0 2 * * *'  # 每天 UTC 时间 2:00

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

决策框架

可重用工作流 vs 复合动作

使用可重用工作流当：

  • 标准化跨仓库的整个 CI/CD 作业
  • 需要带有输入/输出的完整作业替换
  • 希望秘密默认继承
  • 编排具有作业级配置的多个步骤

使用复合动作当：

  • 打包 5-20 步序列以供重用
  • 需要在作业内进行步骤级抽象
  • 希望通过市场或私有仓库分发
  • 需要本地文件访问而无需工件
特性 可重用工作流 复合动作
范围 完整作业 步骤序列
触发器 workflow_call uses: 在步骤中
秘密 默认继承 必须显式传递
文件共享 需要工件 相同运行器/工作区

详细模式，参见 references/reusable-workflows.md 和 references/composite-actions.md。

缓存策略

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

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'  # 或 '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。

自托管 vs 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。

并发控制

# 在新推送时取消进行中的运行
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# 每个环境单一部署
jobs:
  deploy:
    concurrency:
      group: production-deployment
      cancel-in-progress: false
    steps: [...]

可重用工作流

定义可重用工作流

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

name: 可重用构建
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  # 仅限同一组织

完整可重用工作流指南，参见 references/reusable-workflows.md。

复合动作

定义复合动作

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

name: '设置项目'
description: '安装依赖并设置环境'

inputs:
  node-version:
    description: 'Node.js 版本'
    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" 标记动作类型
  • shell: 对所有 run 步骤必需
  • 通过 ${{ 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  # 使用环境秘密
    steps:
      - env:
          API_KEY: ${{ secrets.API_KEY }}
        run: ./deploy.sh

OIDC 认证（无长期凭证）

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # 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

最小权限

# 工作流级
permissions:
  contents: read
  pull-requests: write

# 作业级
jobs:
  deploy:
    permissions:
      contents: write
      deployments: write
    steps: [...]

动作固定

# 固定到提交 SHA（非标签）
- 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 "分支：${{ github.ref }}, 事件：${{ 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