github-actions-pipeline-builder

GitHub Actions 流水线构建器

擅长使用 GitHub Actions 构建快速、可靠且安全的生产级 CI/CD 流水线。

适用场景

✅ 适用于：

• 在每次提交时自动运行测试
• 部署到预发布环境/生产环境
• 构建并发布 Docker 镜像
• 自动化版本发布
• 安全扫描和依赖项审计
• 代码质量检查（lint、类型检查）
• 多环境工作流

❌ 不适用于：

• 非 GitHub 仓库（使用 Jenkins、CircleCI 等）
• 更适合专用 CI/CD 工具的复杂流水线
• 自托管运行器（高级模式中介绍）

快速决策树

Does your project need:
├── Testing on every PR? → GitHub Actions
├── Automated deployments? → GitHub Actions
├── Matrix builds (Node 16, 18, 20)? → GitHub Actions
├── Secrets management? → GitHub Actions secrets
├── Multi-cloud deployments? → GitHub Actions + OIDC
└── Sub-second builds? → Consider build caching

---

技术选型

GitHub Actions 与替代方案对比

2024 年选择 GitHub Actions 的原因：

• 原生集成：无需设置第三方服务
• 公共仓库免费：私有仓库每月提供 2000 分钟
• 矩阵构建：并行测试多个版本
• Marketplace：提供 10,000 多个预构建的 Action
• 支持 OIDC：无需密钥的云部署

发展历程：

• 2019 年：GitHub Actions 发布
• 2020 年：成为开源软件项目的标准
• 2022 年：支持 OIDC，实现安全的云身份验证
• 2024 年：成为 GitHub 仓库的事实标准 CI/CD 方案

何时使用替代方案

场景	使用	原因
自托管 GitLab	GitLab CI	原生集成
复杂的企业工作流	Jenkins	更灵活
Bitbucket 仓库	Bitbucket Pipelines	原生集成
超大型仓库（>10GB）	BuildKite	更适合单体仓库

---

常见反模式

反模式 1：不缓存依赖项

新手想法：“每次都重新安装依赖项，以保持一致性”

问题：每次构建都要花费 2-5 分钟安装未更改的依赖项。

错误做法：

# ❌ Slow: Downloads all dependencies every run
- name: Install dependencies
  run: npm install

正确做法：

# ✅ Fast: Cache dependencies, only download changes
- name: Cache node_modules
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

- name: Install dependencies
  run: npm ci  # Faster than npm install

效果：安装时间从 3 分钟缩短至 30 秒。

发展历程：

• 2020 年之前：大多数工作流都没有缓存
• 2020 年起：缓存成为标准做法
• 2024 年：设置 Action 内置缓存功能

---

反模式 2：重复的 YAML（不使用矩阵构建）

问题：为不同的 Node 版本复制粘贴工作流。

错误做法：

# ❌ Duplicated workflows
jobs:
  test-node-16:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm test

  test-node-18:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm test

  test-node-20:
    # ... same steps again

正确做法：

# ✅ DRY: Matrix build
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16, 18, 20]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

优点：YAML 减少 66%，测试并行运行。

---

反模式 3：在代码中保存密钥

问题：API 密钥和令牌硬编码在代码中，在仓库中可见。

表现：安全扫描器发出警报，凭据泄露。

正确做法：

# ✅ Use GitHub Secrets
- name: Deploy to production
  env:
    API_KEY: ${{ secrets.PRODUCTION_API_KEY }}
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }}
  run: |
    ./deploy.sh

设置密钥：

1. 仓库 Settings → Secrets and variables → Actions
2. New repository secret
3. 名称：PRODUCTION_API_KEY，值：sk-...

发展历程：

• 2022 年之前：有些团队会提交 .env 文件
• 2022 年起：GitHub 密钥扫描会阻止包含密钥的提交
• 2024 年：OIDC 消除了对长期有效凭据的需求

---

反模式 4：没有失败通知

问题：CI 静默失败，团队数小时后才发现。

正确做法：

# ✅ Slack notification on failure
- name: Notify on failure
  if: failure()
  uses: slackapi/slack-github-action@v1
  with:
    payload: |
      {
        "text": "❌ Build failed: ${{ github.event.head_commit.message }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*Build Failed*\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View logs>"
            }
          }
        ]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

---

反模式 5：每次提交都运行所有测试

问题：反馈周期太慢（测试套件耗时 10 分钟以上）。

表现：开发者不愿频繁提交。

正确做法：

# ✅ Fast feedback: Run subset on PR, full suite on merge
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  quick-tests:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - run: npm run test:unit  # Fast: 2 minutes

  full-tests:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - run: npm run test  # Slow: 10 minutes (unit + integration + e2e)

替代方案：使用 changed-files Action，仅运行受影响的测试。

---

实现模式

模式 1：基础 CI 流水线

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

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

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run type check
        run: npm run typecheck

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

模式 2：多环境部署

name: Deploy

on:
  push:
    branches:
      - main        # → staging
      - production  # → production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.ref_name }}  # staging or production

    steps:
      - uses: actions/checkout@v3

      - name: Deploy to ${{ github.ref_name }}
        run: |
          if [ "${{ github.ref_name }}" == "production" ]; then
            ./deploy.sh production
          else
            ./deploy.sh staging
          fi
        env:
          API_KEY: ${{ secrets.API_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

模式 3：自动化版本发布

name: Release

on:
  push:
    tags:
      - 'v*'  # Trigger on version tags (v1.0.0)

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # Required for creating releases

    steps:
      - uses: actions/checkout@v3

      - name: Build artifacts
        run: npm run build

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            dist/**
          body: |
            ## What's Changed
            See CHANGELOG.md for details.
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

模式 4：构建并推送 Docker 镜像

name: Docker

on:
  push:
    branches: [main]

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to DockerHub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            myapp:latest
            myapp:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

---

生产环境检查清单

□ Dependency caching configured
□ Matrix builds for multiple versions
□ Secrets stored in GitHub Secrets (not code)
□ Failure notifications (Slack, email, etc.)
□ Deploy previews for pull requests
□ Staging → Production promotion workflow
□ Release automation with versioning
□ Docker layer caching enabled
□ CODEOWNERS file for required reviews
□ Branch protection rules enabled
□ Status checks required before merge
□ Security scanning (Dependabot, CodeQL)

---

适用与不适用场景

场景	是否使用 GitHub Actions？
GitHub 托管的仓库	✅ 是
需要矩阵构建	✅ 是
部署到 AWS/GCP/Azure	✅ 是（使用 OIDC）
GitLab 仓库	❌ 否 - 使用 GitLab CI
超大型单体仓库	⚠️ 可能 - 考虑使用 BuildKite
需要图形界面流水线构建器	❌ 否 - 使用 Jenkins/Azure DevOps

---

参考资料

• /references/advanced-caching.md - 加快构建速度的缓存策略
• /references/oidc-deployments.md - 无密钥云身份验证
• /references/security-hardening.md - 安全最佳实践

脚本

• scripts/workflow_validator.ts - 在本地验证 YAML 语法
• scripts/action_usage_analyzer.ts - 查找过时的 Action

资源

• assets/workflows/ - 可直接使用的工作流模板

---

此技能适用于：CI/CD 流水线 | GitHub Actions 工作流 | 矩阵构建 | 缓存 | 部署 | 发布自动化