CI/CD 集成：让 Git 驱动自动化流水线

# 只拉取最近一次提交
git clone --depth=1 https://github.com/org/repo.git

# 拉取最近 5 次提交（某些场景需要少量历史，如 changelog 生成）
git clone --depth=5 https://github.com/org/repo.git

# 初始化仓库但不检出
git clone --no-checkout https://github.com/org/monorepo.git
cd monorepo

# 启用 sparse checkout
git sparse-checkout init --cone

# 只检出 services/auth 和 libs/core 两个目录
git sparse-checkout set services/auth libs/core

# 执行检出
git checkout

# 首次构建：完整克隆
git clone https://github.com/org/repo.git
cd repo

# 后续构建：只拉取增量
git fetch origin main
git checkout FETCH_HEAD

# 或者更精确地：拉取特定提交
git fetch origin abc1234
git checkout FETCH_HEAD

steps:
  # 基础用法：浅克隆，depth=1
  - uses: actions/checkout@v4

  # 完整克隆：获取全部历史（用于 changelog、blame 等）
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

  # 拉取最近 10 条历史
  - uses: actions/checkout@v4
    with:
      fetch-depth: 10

  # 检出子模块
  - uses: actions/checkout@v4
    with:
      submodules: true          # 递归检出所有子模块
      # 或
      submodules: recursive     # 等同于 true，递归检出

  # 检出其他仓库的代码（跨仓库操作）
  - uses: actions/checkout@v4
    with:
      repository: org/other-repo
      ref: v2.0.0               # 检出特定 tag
      token: ${{ secrets.PAT }} # 需要权限令牌
      path: other-repo          # 检出到子目录

on:
  # push 触发：指定分支
  push:
    branches:
      - main                    # main 分支的任何 push
      - 'release/*'             # 匹配 release/1.0, release/2.1 等
      - '!release/experimental' # 排除特定分支（取反）
    tags:
      - 'v*'                    # 匹配 v1.0, v2.3.1 等 tag

  # PR 触发
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main                    # 目标分支为 main 的 PR

  # 手动触发
  workflow_dispatch:
    inputs:
      ref:
        description: 'Git ref to build'
        required: true
        default: 'main'

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      auth: ${{ steps.filter.outputs.auth }}
      core: ${{ steps.filter.outputs.core }}
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          filters: |
            auth:
              - 'services/auth/**'
            core:
              - 'libs/core/**'

  build-auth:
    needs: changes
    if: ${{ needs.changes.outputs.auth == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Building auth service..."

jobs:
  test:
    strategy:
      matrix:
        # 维度一：运行环境
        os: [ubuntu-latest, macos-latest, windows-latest]
        # 维度二：Node.js 版本
        node-version: [18, 20, 22]
        # 排除特定组合
        exclude:
          - os: windows-latest
            node-version: 18
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci && npm test

  # 基于分支的条件构建
  deploy:
    needs: test
    runs-on: ubuntu-latest
    # 只有 main 分支和 release 分支才部署
    if: |
      github.ref == 'refs/heads/main' ||
      startsWith(github.ref, 'refs/heads/release/')
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh

variables:
  # Git 策略：clone / fetch / none
  GIT_STRATEGY: fetch

  # 浅克隆深度：0 表示完整克隆
  GIT_DEPTH: 1

  # 子模块策略：none / normal / recursive
  GIT_SUBMODULE_STRATEGY: recursive

  # checkout 路径
  GIT_CHECKOUT: "true"

  # 清理策略：flags 控制清理行为
  GIT_CLEAN_FLAGS: -ffdx -e cache/

stages:
  - build
  - test
  - review
  - staging
  - production

# 所有分支都执行的构建和测试
build:
  stage: build
  script:
    - make build
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"

test:
  stage: test
  script:
    - make test
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"

# 仅 main/release 分支部署到 staging
deploy:staging:
  stage: staging
  script:
    - ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
    - if: $CI_COMMIT_BRANCH =~ /^release\//
  environment:
    name: staging

# 仅 tag 触发生产部署，且需要手动确认
deploy:production:
  stage: production
  script:
    - ./deploy.sh production
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  when: manual                    # 需要手动点击确认
  environment:
    name: production

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [name: '*/main'],           // 要检出的分支
                    extensions: [
                        // 浅克隆
                        [$class: 'CloneOption',
                         depth: 1,
                         shallow: true,
                         noTags: false,
                         honorRefspec: true],
                        // 子模块
                        [$class: 'SubmoduleOption',
                         recursiveSubmodules: true,
                         trackingSubmodules: false],
                        // sparse checkout
                        [$class: 'SparseCheckoutPaths',
                         sparseCheckoutPaths: [
                             [path: 'services/auth/'],
                             [path: 'libs/core/']
                         ]],
                        // 清理策略
                        [$class: 'CleanBeforeCheckout'],
                        // 检出到子目录
                        [$class: 'RelativeTargetDirectory',
                         relativeTargetDir: 'src']
                    ],
                    userRemoteConfigs: [
                        url: 'https://github.com/org/repo.git',
                        credentialsId: 'github-token'
                    ]
                ])
            }
        }

        stage('Build') {
            steps {
                dir('src') {
                    sh 'make build'
                }
            }
        }
    }
}

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                // 简写：自动从 SCM 触发配置中获取仓库信息
                checkout scm

                sh 'make build && make test'
            }
        }
    }
}

pipeline {
    agent any

    // 所有分支共用的构建和测试
    stages {
        stage('Build & Test') {
            steps {
                sh 'make build && make test'
            }
        }

        // 仅 main 和 release 分支部署
        stage('Deploy') {
            when {
                anyOf {
                    branch 'main'
                    branch pattern: 'release/*', comparator: 'GLOB'
                }
            }
            steps {
                sh './deploy.sh'
            }
        }

        // 仅 tag 触发正式发布
        stage('Release') {
            when {
                buildingTag()
            }
            steps {
                sh './release.sh'
            }
        }
    }
}

# k8s/production/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: auth-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: auth-service
  template:
    spec:
      containers:
        - name: auth-service
          image: registry.example.com/auth:v2.1.0   # 镜像版本
          ports:
            - containerPort: 8080

# ArgoCD Application 定义
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: auth-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/org/k8s-configs.git
    targetRevision: main          # 监听 main 分支
    path: k8s/production          # 配置路径
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true                 # 自动删除 Git 中已不存在的资源
      selfHeal: true              # 自动纠正手动修改（状态收敛）
      allowEmpty: false
    syncOptions:
      - CreateNamespace=true