github-actions-pipeline-builder
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGitHub 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 cachingDoes 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 cachingTechnology 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
何时使用替代方案
| Scenario | Use | Why |
|---|---|---|
| Self-hosted GitLab | GitLab CI | Native integration |
| Complex enterprise workflows | Jenkins | More flexible |
| Bitbucket repos | Bitbucket Pipelines | Native integration |
| Extremely large repos (>10GB) | BuildKite | Better for monorepos |
| 场景 | 推荐工具 | 原因 |
|---|---|---|
| 自托管GitLab | GitLab 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**:
```yamljobs:
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 buildyaml
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 buildPattern 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=maxyaml
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=maxProduction 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
适用与不适用场景对比
| Scenario | Use 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
参考资料
- - Cache strategies for faster builds
/references/advanced-caching.md - - Keyless cloud authentication
/references/oidc-deployments.md - - Security best practices
/references/security-hardening.md
- - 加速构建的缓存策略
/references/advanced-caching.md - - 无密钥云认证
/references/oidc-deployments.md - - 安全最佳实践
/references/security-hardening.md
Scripts
脚本工具
- - Validate YAML syntax locally
scripts/workflow_validator.ts - - Find outdated actions
scripts/action_usage_analyzer.ts
- - 本地验证YAML语法
scripts/workflow_validator.ts - - 查找过时的Actions
scripts/action_usage_analyzer.ts
Assets
资源文件
- - Ready-to-use workflow templates
assets/workflows/
This skill guides: CI/CD pipelines | GitHub Actions workflows | Matrix builds | Caching | Deployments | Release automation
- - 即用型工作流模板
assets/workflows/
本指南涵盖:CI/CD流水线 | GitHub Actions工作流 | Matrix builds | 缓存 | 部署 | 发布自动化