CI/CD 流水线设计：GitHub Actions 实战

Workflow（工作流）
  │
  ├── Job A（任务）
  │     ├── Step 1 → Action: checkout 代码
  │     ├── Step 2 → Action: setup Go 环境
  │     └── Step 3 → Shell: go test ./...
  │
  └── Job B（任务）
        ├── Step 1 → Action: 下载构建产物
        └── Step 2 → Shell: 部署到服务器

name: CI

# ── 多触发条件（满足任一即触发）──
on:
  # 1. 代码推送
  push:
    branches:
      - main
      - 'release/*'
    paths:
      - '**.go'
      - 'go.mod'
      - 'go.sum'
    paths-ignore:
      - '**.md'
      - 'docs/**'

  # 2. Pull Request
  pull_request:
    branches: [main, develop]
    types: [opened, synchronize, reopened]

  # 3. 定时任务（Cron 语法，UTC 时区）
  schedule:
    # 每天北京时间 08:00 执行（UTC 00:00）
    - cron: '0 0 * * *'

  # 4. 手动触发
  workflow_dispatch:
    inputs:
      environment:
        description: '部署环境'
        required: true
        type: choice
        options:
          - staging
          - production
      debug_mode:
        description: '启用调试'
        required: false
        type: boolean
        default: false

  # 5. 发布 Release
  release:
    types: [published]

# .github/workflows/go-ci.yml
name: Go CI

on:
  push:
    branches: [main]
    paths: ['**.go', 'go.mod', 'go.sum', '.github/workflows/go-ci.yml']
  pull_request:
    branches: [main]

env:
  GO_VERSION: '1.22'
  REGISTRY: ghcr.io

jobs:
  # ──────────────────────────────────────────
  # Job 1: 代码检查
  # ──────────────────────────────────────────
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: true

      - name: Run golangci-lint
        uses: golangci/golangci-lint-action@v6
        with:
          version: v1.59
          args: --timeout=5m

  # ──────────────────────────────────────────
  # Job 2: 单元测试 + 覆盖率
  # ──────────────────────────────────────────
  test:
    name: Test
    runs-on: ubuntu-latest
    services:
      # 启动 PostgreSQL 容器供测试使用
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5          

    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: true

      - name: Download dependencies
        run: go mod download

      - name: Run tests with coverage
        env:
          DB_HOST: localhost
          DB_PORT: 5432
          DB_PASSWORD: testpass
          DB_NAME: testdb
        run: |
          go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
          go tool cover -func=coverage.out          

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.out
          token: ${{ secrets.CODECOV_TOKEN }}

  # ──────────────────────────────────────────
  # Job 3: 多平台构建 + 镜像推送
  # ──────────────────────────────────────────
  build:
    name: Build & Push
    needs: [lint, test]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    strategy:
      matrix:
        target:
          - goos: linux
            goarch: amd64
          - goos: linux
            goarch: arm64

    steps:
      - uses: actions/checkout@v4

      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: ${{ env.GO_VERSION }}
          cache: true

      - name: Build binary
        env:
          CGO_ENABLED: 0
          GOOS: ${{ matrix.target.goos }}
          GOARCH: ${{ matrix.target.goarch }}
        run: |
          LDFLAGS="-s -w -X main.Version=${GITHUB_REF_NAME} -X main.Commit=${GITHUB_SHA::8}"
          go build -ldflags="$LDFLAGS" -o app-${{ matrix.target.goos }}-${{ matrix.target.goarch }} ./cmd/server          

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=sha,prefix={{branch}}-
            type=raw,value=latest,enable={{is_default_branch}}            

      - name: Build and push image
        uses: docker/build-push-action@v6
        with:
          context: .
          platforms: linux/${{ matrix.target.goarch }}
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

push / pull_request
        │
        ▼
   ┌─────────┐     ┌─────────┐
   │  Lint   │     │  Test   │   ← 并行执行，互不阻塞
   └────┬────┘     └────┬────┘
        │               │
        └──────┬────────┘
               │  needs: [lint, test]
               ▼
        ┌─────────────┐
        │   Build     │     ← matrix 并行构建 amd64 + arm64
        │  (x2 jobs)  │
        └─────────────┘
               │
               ▼
        推送镜像到 GHCR

# .github/workflows/hugo-deploy.yml
name: Hugo Deploy

on:
  push:
    branches: [main]
    paths:
      - 'content/**'
      - 'static/**'
      - 'layouts/**'
      - 'config.toml'
      - 'hugo.toml'
      - '.github/workflows/hugo-deploy.yml'
  workflow_dispatch:
    inputs:
      target:
        description: '部署目标'
        required: true
        type: choice
        options:
          - github-pages
          - vps
          - both

# 设置 Workflow 级权限
permissions:
  contents: read
  pages: write
  id-token: write

# 同一时间只允许一个部署并发
concurrency:
  group: pages
  cancel-in-progress: false

env:
  HUGO_VERSION: '0.129.0'

jobs:
  # ──────────────────────────────────────────
  # Job 1: 构建 Hugo 站点
  # ──────────────────────────────────────────
  build:
    name: Build Hugo Site
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true        # 获取 Hugo 主题子模块
          fetch-depth: 0          # 获取完整 Git 历史（启用 lastmod）

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true           # PaperMod 主题需要 extended 版本

      - name: Setup Go cache
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/go-build
            ~/go/pkg/mod            
          key: ${{ runner.os }}-hugo-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-hugo-            

      - name: Build
        run: |
          hugo \
            --minify \
            --baseURL "https://www.sre.wang/" \
            --enableGitInfo          

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # ──────────────────────────────────────────
  # Job 2: 部署到 GitHub Pages
  # ──────────────────────────────────────────
  deploy-pages:
    name: Deploy to GitHub Pages
    needs: build
    runs-on: ubuntu-latest
    if: >-
      github.event_name == 'push' ||
      (github.event_name == 'workflow_dispatch' &&
       (github.event.inputs.target == 'github-pages' ||
        github.event.inputs.target == 'both'))      
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # ──────────────────────────────────────────
  # Job 3: 部署到 VPS（通过 rsync over SSH）
  # ──────────────────────────────────────────
  deploy-vps:
    name: Deploy to VPS
    needs: build
    runs-on: ubuntu-latest
    if: >-
      github.event_name == 'push' ||
      (github.event_name == 'workflow_dispatch' &&
       (github.event.inputs.target == 'vps' ||
        github.event.inputs.target == 'both'))      
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: github-pages

      - name: Deploy via rsync
        uses: burnett01/rsync-deployments@7.0.1
        with:
          switches: -avzr --delete
          path: ./
          remote_path: /var/www/sre.wang/
          remote_host: ${{ secrets.VPS_HOST }}
          remote_user: ${{ secrets.VPS_USER }}
          remote_key: ${{ secrets.VPS_SSH_KEY }}

- uses: actions/setup-go@v5
  with:
    go-version: '1.22'
    cache: true    # setup-go 内置缓存，自动缓存 ~/go/pkg/mod 和 ~/.cache/go-build

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

- name: Cache Docker layers
  uses: actions/cache@v4
  with:
    path: /tmp/.buildx-cache
    key: ${{ runner.os }}-buildx-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-buildx-      

# 缓存键的三层设计：精确匹配 → 部分匹配 → 系统级兜底
key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}       # 精确：依赖文件变了就新建缓存
restore-keys: |
  ${{ runner.os }}-go-                                        # 部分：依赖文件变了也能恢复大部分缓存
  ${{ runner.os }}-                                           # 兜底：至少恢复系统级缓存  

steps:
  - name: Deploy to production
    env:
      DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}     # 数据库密码
      API_KEY: ${{ secrets.API_KEY }}                   # 第三方 API Key
      DEPLOY_SSH_KEY: ${{ secrets.VPS_SSH_KEY }}        # SSH 私钥
    run: ./deploy.sh

# Go CI 中使用 OIDC 推送镜像到 AWS ECR
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write     # 必须启用，用于获取 OIDC 令牌
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
          aws-region: ap-northeast-1

      - name: Login to ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: 123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/app:latest

传统方式（长期密钥）：
  GitHub Secrets → AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
  ┌──────────┐         ┌──────────┐
  │  CI Job   │ ──key──→│   AWS    │   密钥泄露 = 账户沦陷
  └──────────┘         └──────────┘

OIDC 方式（短期令牌）：
  ┌──────────┐  OIDC Token  ┌──────────┐  AssumeRole  ┌──────────┐
  │  CI Job   │ ──────────→ │  AWS IAM  │ ───────────→ │   AWS    │
  └──────────┘  (JWT, 1h)   └──────────┘  (临时凭证)    └──────────┘
  无需存储任何长期密钥         信任关系预先配置            令牌 1 小时过期

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:lorock/sre.wang:ref:refs/heads/main"
        }
      }
    }
  ]
}

.github/
├── workflows/
│   ├── go-ci.yml              # Go 项目 CI 流水线
│   ├── hugo-deploy.yml        # Hugo 站点部署流水线
│   ├── release.yml             # 发布流水线（tag 触发）
│   └── scheduled-check.yml     # 定期安全扫描
└── actions/                    # 自定义 Composite Action（可选）
    └── setup-env/
        └── action.yml