GitHubActions技能Skill github-actions

name: github-actions description: GitHub Actions 工作流设计，作业结构，触发器，可重用工作流，以及最佳实践。在创建或审查 CI/CD 管道时使用。 allowed-tools: Read, Write, Glob, Grep, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs

GitHub Actions 技能

设计和实现用于 CI/CD 自动化的 GitHub Actions 工作流。

何时使用此技能

关键词: github actions, ci/cd, 工作流, 管道, 构建, 部署, 持续集成, 持续部署, yaml 工作流, 作业, 步骤, 运行器, 矩阵, 可重用工作流

使用此技能当:

• 创建新的 GitHub Actions 工作流
• 审查现有的工作流文件
• 设计存储库的 CI/CD 管道
• 设置构建/测试/部署自动化
• 实现可重用工作流模式

强制：文档优先方法

在创建工作流之前：

1. 通过 MCP 服务器验证语法（使用 context7 获取 GitHub Actions 文档）
2. 检查存储库中的现有模式
3. 尽可能使用官方 actions（如 actions/checkout, actions/setup-node, 等）

工作流结构概述

name: 工作流名称

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

permissions:
  contents: read

jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 步骤名称
        run: echo "Hello"

关键概念

触发器 (on)

触发器	使用案例
push	在推送到指定分支时运行
pull_request	在 PR 事件上运行
workflow_dispatch	手动触发
schedule	基于 Cron 的调度
workflow_call	由其他工作流调用（可重用）

作业配置

设置	目的
runs-on	运行器环境（ubuntu-latest, windows-latest, macos-latest）
needs	作业依赖
if	条件执行
strategy.matrix	矩阵构建
environment	部署环境与保护规则

常见 Actions

Action	目的
actions/checkout@v4	检出存储库
actions/setup-node@v4	设置 Node.js
actions/setup-python@v5	设置 Python
actions/setup-dotnet@v4	设置 .NET
actions/cache@v4	缓存依赖项
actions/upload-artifact@v4	上传构建产物

最佳实践

安全

permissions:
  contents: read  # 最小权限

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4  # 固定到特定版本

缓存

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

矩阵构建

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

可重用工作流

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci && npm test

调用可重用工作流:

jobs:
  call-test:
    uses: ./.github/workflows/reusable-test.yml
    with:
      node-version: '20'
    secrets: inherit

工作流模式

PR 验证

name: PR 验证
on:
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  build:
    needs: [lint, test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build

发布工作流

name: 发布
on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: 创建发布
        uses: softprops/action-gh-release@v1
        with:
          files: dist/*
          generate_release_notes: true

常见问题

问题	解决方案
权限被拒绝	添加包含所需访问权限的 permissions 块
找不到 Action	检查 Action 版本和存储库
缓存不工作	验证 key 模式是否匹配文件路径
作业依赖失败	检查 needs 引用和作业名称

MCP 研究

对于当前的 GitHub Actions 模式：

perplexity: "GitHub Actions 最佳实践 2026"
context7: "github-actions"（用于官方文档）

版本历史

• v1.0.0 (2026-01-17): 初始版本

---

最后更新: 2026-01-17