github-actions-pipeline-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Actions Pipeline Builder

GitHub Actions 流水线构建指南

Expert in building production-grade CI/CD pipelines with GitHub Actions that are fast, reliable, and secure.
本指南专注于使用GitHub Actions构建快速、可靠且安全的生产级CI/CD流水线。

When to Use

适用场景

Use for:
  • Automated testing on every commit
  • Deployment to staging/production
  • Docker image building and publishing
  • Release automation with versioning
  • Security scanning and dependency audits
  • Code quality checks (linting, type checking)
  • Multi-environment workflows
NOT for:
  • Non-GitHub repositories (use Jenkins, CircleCI, etc.)
  • Complex pipelines better suited for dedicated CI/CD tools
  • Self-hosted runners (covered in advanced patterns)
适用场景:
  • 每次提交时的自动化测试
  • 部署到预发布/生产环境
  • Docker镜像构建与发布
  • 带版本控制的发布自动化
  • 安全扫描与依赖审计
  • 代码质量检查(代码规范检查、类型检查)
  • 多环境工作流
不适用场景:
  • 非GitHub仓库(请使用Jenkins、CircleCI等工具)
  • 更适合专用CI/CD工具的复杂流水线
  • 自托管运行器(相关内容请参考高级模式章节)

Quick Decision Tree

快速决策树

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

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

Technology Selection

技术选型

GitHub Actions vs Alternatives

GitHub Actions 与替代方案对比

Why GitHub Actions in 2024:
  • Native integration: No third-party setup
  • Free for public repos: 2000 minutes/month for private
  • Matrix builds: Test multiple versions in parallel
  • Marketplace: 10,000+ pre-built actions
  • OIDC support: Keyless cloud deployments
Timeline:
  • 2019: GitHub Actions released
  • 2020: Became standard for OSS projects
  • 2022: OIDC support for secure cloud auth
  • 2024: De facto CI/CD for GitHub repos
2024年选择GitHub Actions的原因:
  • 原生集成: 无需第三方配置
  • 公共仓库免费: 私有仓库每月提供2000分钟运行时长
  • Matrix builds: 并行测试多个版本
  • Marketplace: 拥有10000+预构建Actions
  • OIDC支持: 无密钥云部署
发展时间线:
  • 2019年: GitHub Actions发布
  • 2020年: 成为开源项目的标准工具
  • 2022年: 添加OIDC支持以实现安全云认证
  • 2024年: 成为GitHub仓库的事实标准CI/CD工具

When to Use Alternatives

何时使用替代方案

ScenarioUseWhy
Self-hosted GitLabGitLab CINative integration
Complex enterprise workflowsJenkinsMore flexible
Bitbucket reposBitbucket PipelinesNative integration
Extremely large repos (>10GB)BuildKiteBetter for monorepos

场景推荐工具原因
自托管GitLabGitLab CI原生集成
复杂企业级工作流Jenkins灵活性更高
Bitbucket仓库Bitbucket Pipelines原生集成
超大型仓库(>10GB)BuildKite更适合单体仓库

Common Anti-Patterns

常见反模式

Anti-Pattern 1: No Dependency Caching

反模式1:未使用依赖缓存

Novice thinking: "Install dependencies fresh every time for consistency"
Problem: Wastes 2-5 minutes per build installing unchanged dependencies.
Wrong approach:
yaml
undefined
新手误区: "为了一致性,每次都重新安装依赖"
问题: 每次构建都安装未变更的依赖,浪费2-5分钟时间。
错误做法:
yaml
undefined

❌ Slow: Downloads all dependencies every run

❌ Slow: Downloads all dependencies every run

  • name: Install dependencies run: npm install

**Correct approach**:
```yaml
  • name: Install dependencies run: npm install

**正确做法**:
```yaml

✅ Fast: Cache dependencies, only download changes

✅ 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

**Impact**: Reduces install time from 3 minutes → 30 seconds.

**Timeline**:
- Pre-2020: Most workflows had no caching
- 2020+: Caching became standard
- 2024: Setup actions include built-in caching

---
  • 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年: Setup Actions已内置缓存功能

---

Anti-Pattern 2: Duplicate YAML (No Matrix Builds)

反模式2:重复YAML配置(未使用Matrix Builds)

Problem: Copy-paste workflows for different Node versions.
Wrong approach:
yaml
undefined
问题: 为不同Node版本复制粘贴工作流配置。
错误做法:
yaml
undefined

❌ Duplicated workflows

❌ 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

**Correct approach**:
```yaml
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

**正确做法**:
```yaml

✅ DRY: Matrix build

✅ 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

**Benefits**: 66% less YAML, tests run in parallel.

---
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%,测试并行运行。

---

Anti-Pattern 3: Secrets in Code

反模式3:代码中硬编码密钥

Problem: Hardcoded API keys, tokens visible in repo.
Symptoms: Security scanner alerts, leaked credentials.
Correct approach:
yaml
undefined
问题: 硬编码的API密钥、令牌暴露在仓库中。
症状: 安全扫描器发出警报,凭证泄露。
正确做法:
yaml
undefined

✅ Use GitHub Secrets

✅ 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

**Setting secrets**:
1. Repo Settings → Secrets and variables → Actions
2. New repository secret
3. Name: `PRODUCTION_API_KEY`, Value: `sk-...`

**Timeline**:
- Pre-2022: Some teams committed .env files
- 2022+: GitHub secret scanning blocks commits with keys
- 2024: OIDC eliminates need for long-lived credentials

---
  • name: Deploy to production env: API_KEY: ${{ secrets.PRODUCTION_API_KEY }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY }} run: | ./deploy.sh

**设置密钥步骤**:
1. 仓库设置 → 密钥和变量 → Actions
2. 新建仓库密钥
3. 名称: `PRODUCTION_API_KEY`, 值: `sk-...`

**时间线**:
- 2022年前: 部分团队会提交.env文件
- 2022年起: GitHub密钥扫描会阻止包含密钥的提交
- 2024年: OIDC消除了对长期凭证的需求

---

Anti-Pattern 4: No Failure Notifications

反模式4:无失败通知机制

Problem: CI fails silently, team doesn't notice for hours.
Correct approach:
yaml
undefined
问题: CI构建失败后无通知,团队数小时后才发现。
正确做法:
yaml
undefined

✅ Slack notification on failure

✅ 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 }}

---
  • 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 }}

---

Anti-Pattern 5: Running All Tests on Every Commit

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

Problem: Slow feedback loop (10+ minute test suites).
Symptom: Developers avoid committing frequently.
Correct approach:
yaml
undefined
问题: 反馈循环缓慢(测试套件耗时10+分钟)。
症状: 开发者避免频繁提交代码。
正确做法:
yaml
undefined

✅ Fast feedback: Run subset on PR, full suite on merge

✅ 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)

**Alternative**: Use changed-files action to run only affected tests.

---
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仅运行受影响的测试。

---

Implementation Patterns

实现模式

Pattern 1: Basic CI Pipeline

模式1:基础CI流水线

yaml
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
yaml
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

Pattern 2: Multi-Environment Deployment

模式2:多环境部署

yaml
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 }}
yaml
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 }}

Pattern 3: Release Automation

模式3:发布自动化

yaml
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 }}
yaml
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 }}

Pattern 4: Docker Build & Push

模式4:Docker构建与推送

yaml
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

yaml
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

Production Checklist

生产环境检查清单

□ 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)

□ 已配置依赖缓存
□ 已配置多版本matrix builds
□ 密钥存储在GitHub Secrets中(而非代码里)
□ 已设置失败通知(Slack、邮件等)
□ 已配置拉取请求的部署预览
□ 已设置预发布→生产环境的晋升工作流
□ 已配置带版本控制的发布自动化
□ 已启用Docker层缓存
□ 已配置CODEOWNERS文件以要求代码评审
□ 已启用分支保护规则
□ 已设置合并前必须通过状态检查
□ 已启用安全扫描(Dependabot、CodeQL)

When to Use vs Avoid

适用与不适用场景对比

ScenarioUse GitHub Actions?
GitHub-hosted repo✅ Yes
Need matrix builds✅ Yes
Deploying to AWS/GCP/Azure✅ Yes (with OIDC)
GitLab repo❌ No - use GitLab CI
Extremely large monorepo⚠️ Maybe - consider BuildKite
Need GUI pipeline builder❌ No - use Jenkins/Azure DevOps

场景是否使用GitHub Actions?
GitHub托管仓库✅ 是
需要matrix builds✅ 是
部署到AWS/GCP/Azure✅ 是(搭配OIDC)
GitLab仓库❌ 否 - 使用GitLab CI
超大型单体仓库⚠️ 视情况而定 - 可考虑BuildKite
需要GUI流水线构建器❌ 否 - 使用Jenkins/Azure DevOps

References

参考资料

  • /references/advanced-caching.md
    - Cache strategies for faster builds
  • /references/oidc-deployments.md
    - Keyless cloud authentication
  • /references/security-hardening.md
    - Security best practices
  • /references/advanced-caching.md
    - 加速构建的缓存策略
  • /references/oidc-deployments.md
    - 无密钥云认证
  • /references/security-hardening.md
    - 安全最佳实践

Scripts

脚本工具

  • scripts/workflow_validator.ts
    - Validate YAML syntax locally
  • scripts/action_usage_analyzer.ts
    - Find outdated actions
  • scripts/workflow_validator.ts
    - 本地验证YAML语法
  • scripts/action_usage_analyzer.ts
    - 查找过时的Actions

Assets

资源文件

  • assets/workflows/
    - Ready-to-use workflow templates

This skill guides: CI/CD pipelines | GitHub Actions workflows | Matrix builds | Caching | Deployments | Release automation
  • assets/workflows/
    - 即用型工作流模板

本指南涵盖:CI/CD流水线 | GitHub Actions工作流 | Matrix builds | 缓存 | 部署 | 发布自动化