ci-cd

CI/CD 流水线

关于 GitHub Actions、GitLab CI 和其他平台上的 CI/CD 流水线设计、优化、安全和故障排查的综合指南。

核心工作流

1. 创建新流水线

决策树：

What are you building?
├── Node.js/Frontend → GitHub: templates/github-actions/node-ci.yml | GitLab: templates/gitlab-ci/node-ci.yml
├── Python → GitHub: templates/github-actions/python-ci.yml | GitLab: templates/gitlab-ci/python-ci.yml
├── Go → GitHub: templates/github-actions/go-ci.yml | GitLab: templates/gitlab-ci/go-ci.yml
├── Docker Image → GitHub: templates/github-actions/docker-build.yml | GitLab: templates/gitlab-ci/docker-build.yml
├── Other → Follow the pipeline design pattern below

基本流水线结构：

# 1. Fast feedback (lint, format) - <1 min
# 2. Unit tests - 1-5 min
# 3. Integration tests - 5-15 min
# 4. Build artifacts
# 5. E2E tests (optional, main branch only) - 15-30 min
# 6. Deploy (with approval gates)

关键原则（来自 references/best_practices.md）：

• 快速失败：先运行成本较低的验证
• 并行执行：移除不必要的作业依赖
• 缓存依赖项：使用 actions/cache 或 GitLab 缓存（策略参见 references/optimization.md）
• 使用构建产物：构建一次，多次部署
• 尽早添加安全扫描：SAST/DAST/SCA 集成参见 references/devsecops.md

2. 优化流水线性能

快速见效检查清单：

• 添加依赖项缓存（构建速度提升 50-90%）
• 移除不必要的 needs 依赖
• 添加路径筛选器，跳过不必要的运行
• 使用 npm ci 代替 npm install
• 添加作业超时设置，防止构建挂起
• 启用并发取消，取消重复运行

分析现有流水线：

# Use the pipeline analyzer script
python3 scripts/pipeline_analyzer.py --platform github --workflow .github/workflows/ci.yml

常见优化方式（详见 references/optimization.md）：

• 测试缓慢： 使用矩阵构建拆分测试
• 重复安装依赖项： 添加缓存
• 顺序执行的作业： 通过正确设置 needs 并行执行
• 每次 PR 都运行完整测试套件： 使用路径筛选器或测试影响分析

详细的缓存策略、并行化技巧和性能调优方法请参见 optimization.md。

3. 保障流水线安全

基本安全检查清单：

• 使用 OIDC 代替静态凭据
• 将 actions/includes 固定到提交 SHA
• 使用最小权限
• 启用密钥扫描
• 添加漏洞扫描（依赖项、容器）
• 实施分支保护
• 将测试和部署工作流分开

快速设置 - OIDC 身份验证：

GitHub Actions → AWS：

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/GitHubActionsRole
      aws-region: us-east-1

密钥管理：

• 存储在平台的密钥存储中（GitHub Secrets、GitLab CI/CD Variables）
• 在 GitLab 中标记为“masked”
• 使用特定环境的密钥
• 定期轮换（每 90 天）
• 切勿记录密钥

全面的安全模式、供应链安全和密钥管理请参见 security.md。

4. 排查流水线故障

系统化处理方法：

步骤 1：检查流水线状态

gh run list --limit 20    # Recent runs with status (success/failure rates)
gh run view <run-id>      # Detailed run info and failure logs
gh workflow list           # All configured workflows

步骤 2：识别故障类型

错误模式	常见原因	快速修复
"Module not found"	缺少依赖项或缓存问题	清除缓存，运行 npm ci
"Timeout"	作业耗时过长	添加缓存，延长超时时间
"Permission denied"	缺少权限	添加到 permissions: 块中
"Cannot connect to Docker daemon"	Docker 不可用	使用正确的运行器或 DinD
间歇性故障	不稳定的测试或竞争条件	添加重试，修复时序问题

步骤 3：启用调试日志

GitHub Actions：

# Add repository secrets:
# ACTIONS_RUNNER_DEBUG = true
# ACTIONS_STEP_DEBUG = true

GitLab CI：

variables:
  CI_DEBUG_TRACE: "true"

步骤 4：在本地复现

# GitHub Actions - use act
act -j build

# Or Docker
docker run -it ubuntu:latest bash
# Then manually run the failing steps

全面的问题诊断、平台特定问题和解决方案请参见 troubleshooting.md。

5. 实施部署工作流

部署模式选择：

模式	使用场景	复杂度	风险
直接部署	简单应用、低流量	低	中
蓝绿部署	要求零停机时间	中	低
金丝雀部署	渐进式发布、监控	高	非常低
滚动部署	Kubernetes、容器	中	低

基本部署结构：

deploy:
  needs: [build, test]
  if: github.ref == 'refs/heads/main'
  environment:
    name: production
    url: https://example.com
  steps:
    - name: Download artifacts
    - name: Deploy
    - name: Health check
    - name: Rollback on failure

多环境设置：

• 开发环境： 在 develop 分支上自动部署
• 预发布环境： 在 main 上自动部署，要求测试通过
• 生产环境： 需要手动审批，必须进行冒烟测试

详细的部署模式和环境管理请参见 best_practices.md。

6. 实施 DevSecOps 安全扫描

安全扫描类型：

扫描类型	目的	运行时机	速度	工具
密钥扫描	查找暴露的凭据	每次提交	快（<1 分钟）	TruffleHog、Gitleaks
SAST	查找代码漏洞	每次提交	中等（5-15 分钟）	CodeQL、Semgrep、Bandit、Gosec
SCA	查找依赖项漏洞	每次提交	快（1-5 分钟）	npm audit、pip-audit、Snyk
容器扫描	查找镜像漏洞	构建后	中等（5-10 分钟）	Trivy、Grype
DAST	查找运行时漏洞	仅计划任务/主分支	慢（15-60 分钟）	OWASP ZAP

快速设置 — 为现有流水线添加安全扫描：

GitHub Actions：

jobs:
  # Add before build job
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: trufflesecurity/trufflehog@main
      - uses: gitleaks/gitleaks-action@v2

  sast:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript  # or python, go
      - uses: github/codeql-action/analyze@v3

  build:
    needs: [secret-scan, sast]  # Add dependencies

GitLab CI：

stages:
  - security  # Add before other stages
  - build
  - test

# Secret scanning
secret-scan:
  stage: security
  image: trufflesecurity/trufflehog:latest
  script:
    - trufflehog filesystem . --json --fail

# SAST
sast:semgrep:
  stage: security
  image: returntocorp/semgrep
  script:
    - semgrep scan --config=auto .

# Use GitLab templates
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

全面的安全流水线模板：

• GitHub Actions： templates/github-actions/security-scan.yml - 包含所有扫描阶段的完整 DevSecOps 流水线
• GitLab CI： templates/gitlab-ci/security-scan.yml - 包含 GitLab 安全模板的完整 DevSecOps 流水线

安全门控模式：

添加一个安全门控作业，评估所有安全扫描结果，并在发现严重问题时使流水线失败：

security-gate:
  needs: [secret-scan, sast, sca, container-scan]
  script:
    # Check for critical vulnerabilities
    # Parse JSON reports and evaluate thresholds
    # Fail if critical issues found

特定语言的安全工具：

• Node.js： CodeQL、Semgrep、npm audit、eslint-plugin-security
• Python： CodeQL、Semgrep、Bandit、pip-audit、Safety
• Go： CodeQL、Semgrep、Gosec、govulncheck

所有特定语言的模板现已包含安全扫描阶段。参见：

• templates/github-actions/node-ci.yml
• templates/github-actions/python-ci.yml
• templates/github-actions/go-ci.yml
• templates/gitlab-ci/node-ci.yml
• templates/gitlab-ci/python-ci.yml
• templates/gitlab-ci/go-ci.yml

参阅 devsecops.md，了解全面的 DevSecOps 指南，涵盖所有安全扫描类型、工具比较和实施模式。

快速参考命令

GitHub Actions

# List workflows
gh workflow list

# View recent runs
gh run list --limit 20

# View specific run
gh run view <run-id>

# Re-run failed jobs
gh run rerun <run-id> --failed

# Download logs
gh run view <run-id> --log > logs.txt

# Trigger workflow manually
gh workflow run ci.yml

# Check workflow status
gh run watch

GitLab CI

# View pipelines
gl project-pipelines list

# Pipeline status
gl project-pipeline get <pipeline-id>

# Retry failed jobs
gl project-pipeline retry <pipeline-id>

# Cancel pipeline
gl project-pipeline cancel <pipeline-id>

# Download artifacts
gl project-job artifacts <job-id>

平台特定模式

GitHub Actions

可复用工作流：

# .github/workflows/reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string

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

从另一个工作流调用：

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

GitLab CI

使用 extends 的模板：

.test_template:
  image: node:20
  before_script:
    - npm ci

unit-test:
  extends: .test_template
  script:
    - npm run test:unit

integration-test:
  extends: .test_template
  script:
    - npm run test:integration

使用 needs 的 DAG 流水线：

build:
  stage: build

test:unit:
  stage: test
  needs: [build]

test:integration:
  stage: test
  needs: [build]

deploy:
  stage: deploy
  needs: [test:unit, test:integration]

诊断脚本

脚本	目的	用法
pipeline_analyzer.py	查找优化机会（缓存、并行化、过时的操作）	python3 scripts/pipeline_analyzer.py --platform github --workflow <path>

若要检查流水线健康状况（成功/失败率、失败模式），请使用 gh CLI：gh run list --limit 20、gh run view <run-id>、gh workflow list。

参考文档

• references/best_practices.md — 流水线设计、测试、部署模式、构件处理
• references/security.md — 密钥管理、OIDC、供应链安全、安全流水线模式
• references/devsecops.md — SAST/DAST/SCA 工具（CodeQL、Semgrep、Trivy、Snyk）、安全门控
• references/optimization.md — 缓存策略、并行化、测试拆分、构建优化
• references/troubleshooting.md — 常见问题、Docker 问题、身份验证、平台调试

模板

assets/templates/ 中提供适用于 GitHub Actions 和 GitLab CI 的入门模板：

语言/类型	GitHub Actions	GitLab CI
Node.js	github-actions/node-ci.yml	gitlab-ci/node-ci.yml
Python	github-actions/python-ci.yml	gitlab-ci/python-ci.yml
Go	github-actions/go-ci.yml	gitlab-ci/go-ci.yml
Docker	github-actions/docker-build.yml	gitlab-ci/docker-build.yml
安全	github-actions/security-scan.yml	gitlab-ci/security-scan.yml

所有模板均包含安全扫描、缓存和多环境部署。

常见模式

缓存依赖项

GitHub Actions：

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

GitLab CI：

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/

矩阵构建

GitHub Actions：

strategy:
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [18, 20, 22]
  fail-fast: false

GitLab CI：

test:
  parallel:
    matrix:
      - NODE_VERSION: ['18', '20', '22']

条件执行

GitHub Actions：

- name: Deploy
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'

GitLab CI：

deploy:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual

快速入门

1. 新建流水线： 从 assets/templates/ 中选择一个模板
2. 添加安全扫描： 使用 DevSecOps 模板，或为现有流水线添加安全阶段（参见上文的工作流 6）
3. 优化现有流水线： 运行 scripts/pipeline_analyzer.py
4. 调试问题： 查看 references/troubleshooting.md
5. 提升安全性： 查看 references/security.md 和 references/devsecops.md 检查清单
6. 加快构建速度： 参见 references/optimization.md