github-actions

GitHub Actions 核心知识

深入了解：使用 mcp__documentation__fetch_docs 并指定技术：github-actions，获取完整文档。

基本 CI 工作流

# .github/workflows/ci.yml
name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

使用数据库

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgresql://test:test@localhost:5432/testdb

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx prisma migrate deploy
      - run: npm test

部署工作流

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

矩阵策略

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

可复用工作流

# .github/workflows/test.yml
on:
  workflow_call:

jobs:
  test:
    runs-on: ubuntu-latest
    steps: [...]

# Usage in another workflow
jobs:
  call-tests:
    uses: ./.github/workflows/test.yml

不适用此技能的情况

以下情况请跳过此技能：

• 使用 GitLab CI/CD（.gitlab-ci.yml）——语法不同
• 使用 Jenkins、CircleCI、Travis CI——平台不同
• 配置本地开发环境——使用 docker-compose 技能
• 仅构建 Docker 镜像（无需 CI）——使用 docker 技能
• 使用 Bitbucket Pipelines——平台不同

反模式

反模式	问题	解决方案
未限制权限	安全风险，访问权限过多	为每个作业设置最小化的 permissions:
使用 @v1 等操作标签	更新时可能发生破坏性变更	固定到 SHA：@60edb5dd545a775178f52524783378180af0d1f8
在日志中暴露密钥	凭据泄露	切勿 echo 密钥，仅使用 env:
未设置超时	作业失控运行并消耗分钟数	为作业设置 timeout-minutes: 15
未缓存任何内容	构建缓慢，浪费时间	使用 actions/cache 缓存依赖项
每次提交都运行	浪费 CI 分钟数	使用 paths: 过滤器或仅使用 pull_request:
版本硬编码	环境不一致	使用矩阵策略或环境变量
未限制制品保留时间	存储成本高	为制品设置 retention-days: 7
在代码中存储密钥	安全漏洞	使用 GitHub Secrets，切勿提交
未启用分支保护	可绕过 CI 检查	在分支规则中要求状态检查

快速故障排除

问题	诊断	修复方法
工作流未触发	事件或分支过滤器错误	检查 on: 触发器和分支名称
作业静默失败	脚本错误被忽略	不要使用 `
缓存从未命中	缓存键不断变化	使用稳定的键：hashFiles('**/package-lock.json')
“Resource not accessible”	权限错误	为作业添加所需的 permissions:
PR 中无法使用密钥	Fork 无权访问	使用 pull_request_target（谨慎操作）或跳过需要密钥的步骤
制品上传失败	路径不存在	检查构建输出路径，使用 if: always()
矩阵作业失败	一个配置导致全部失败	使用 fail-fast: false 以继续运行其他作业
工作流耗时过长	未缓存，作业按顺序运行	添加缓存，使用 needs: 并行运行
“Context access might be invalid”	上下文语法错误	使用 ${{ }} 语法，检查上下文是否可用
无法触发另一个工作流	令牌权限不足	使用 PAT，或使用具有写入权限的 GITHUB_TOKEN

生产就绪

安全最佳实践

# Secure workflow
name: CI

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

permissions:
  contents: read
  pull-requests: write

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      # Pin actions to SHA for security
      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
        with:
          node-version: '20'

      # Use environment secrets
      - name: Deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          # Never echo secrets
          ./deploy.sh

缓存策略

jobs:
  build:
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

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

      # Turbo cache for monorepos
      - name: Cache Turbo
        uses: actions/cache@v4
        with:
          path: .turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-

制品管理

jobs:
  build:
    steps:
      - name: Build
        run: npm run build

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: build-${{ github.sha }}
          path: dist/

环境保护

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment:
      name: production
      url: https://example.com
    concurrency:
      group: production-deploy
      cancel-in-progress: false

错误处理

jobs:
  build:
    steps:
      - name: Run tests
        id: tests
        continue-on-error: true
        run: npm test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: coverage/

      - name: Check test status
        if: steps.tests.outcome == 'failure'
        run: |
          echo "Tests failed"
          exit 1

      - name: Notify on failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {"text": "Build failed: ${{ github.repository }}"}
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

Dependabot 配置

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      development-dependencies:
        patterns:
          - "@types/*"
          - "eslint*"
          - "prettier*"

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

发布工作流

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: dist/*
          generate_release_notes: true

监控指标

指标	目标
构建成功率	> 95%
构建时长	< 10min
缓存命中率	> 80%
部署频率	按需

检查清单

• 声明最小权限
• 将操作固定到 SHA
• 日志中未暴露密钥
• 已配置缓存
• 已设置超时
• 错误通知
• 环境保护规则
• 已启用 Dependabot
• 分支保护规则
• 并发控制

参考文档

• 缓存
• 密钥