orchestrate-multi-repo-sdks

编排多仓库 SDK

管理 SDK 生成流程，其中每种语言的 SDK 都位于单独的仓库中（例如，myapi-typescript、myapi-python、myapi-go）。

使用场景

• 不同语言的 SDK 位于单独的仓库中
• 需要由 PR 触发跨仓库的 SDK 生成
• 需要自动协调 PR（在规范 PR 关闭时合并或关闭 SDK PR）
• 不同团队维护不同语言的 SDK
• 用户提到：“多仓库 SDK”“跨仓库工作流”“SDK PR 同步”

架构

┌─────────────────────────────────────────────────────────┐
│                  API Spec Repository                     │
├─────────────────────────────────────────────────────────┤
│  PR opened    │  PR merged/closed    │  Main push       │
│      ↓        │        ↓             │      ↓           │
│  kick-off     │  reconcile-prs       │  sync            │
└───────────────┴──────────────────────┴──────────────────┘
        │                │                    │
        ▼                ▼                    ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ typescript   │  │ python-sdk   │  │ go-sdk       │
│ SDK PR       │  │ SDK PR       │  │ SDK PR       │
└──────────────┘  └──────────────┘  └──────────────┘

工作流 1：启动生成（PR 触发）

当规范 PR 创建时，在每个语言仓库中触发 SDK 生成：

# .github/workflows/kick-off-generation.yaml
name: Kick Off SDK Generation
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  trigger_sdk_repos:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - repo: myapi-typescript
          - repo: myapi-python
          - repo: myapi-go
    steps:
      - name: Trigger SDK generation
        env:
          GH_TOKEN: ${{ secrets.SDK_REPOS_PAT }}
        run: |
          gh workflow run sdk_generation.yaml \
            --repo "your-org/${{ matrix.repo }}" \
            --field feature_branch="${{ github.head_ref }}"

工作流 2：协调 PR（合并/关闭时）

在规范 PR 关闭时，自动合并或关闭 SDK PR：

# .github/workflows/reconcile-prs.yaml
name: Reconcile SDK PRs
on:
  pull_request:
    types: [closed]

jobs:
  manage_sdk_prs:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        repo: [myapi-typescript, myapi-python, myapi-go]
    steps:
      - name: Manage SDK PR
        env:
          GH_TOKEN: ${{ secrets.SDK_REPOS_PAT }}
        run: |
          branch="${{ github.event.pull_request.head.ref }}"
          was_merged="${{ github.event.pull_request.merged }}"

          pr_number=$(gh pr list --repo "your-org/${{ matrix.repo }}" \
            --head "$branch" --json number --jq '.[0].number')

          if [[ -n "$pr_number" ]]; then
            if [[ "$was_merged" == "true" ]]; then
              gh pr merge "$pr_number" --repo "your-org/${{ matrix.repo }}" \
                --squash --delete-branch
            else
              gh pr close "$pr_number" --repo "your-org/${{ matrix.repo }}"
            fi
          fi

SDK 仓库工作流

每个 SDK 仓库都需要一个可调度的工作流：

# .github/workflows/sdk_generation.yaml (in each SDK repo)
name: SDK Generation
on:
  workflow_dispatch:
    inputs:
      feature_branch:
        description: 'Feature branch from spec repo'
        required: false

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Create branch
        if: inputs.feature_branch != ''
        run: git checkout -b "${{ inputs.feature_branch }}"

      - name: Generate SDK
        run: speakeasy run -y
        env:
          SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}

      - name: Create PR
        if: inputs.feature_branch != ''
        run: |
          git add -A && git commit -m "chore: regenerate SDK" || exit 0
          git push -u origin "${{ inputs.feature_branch }}"
          gh pr create --title "SDK update" --body "Auto-generated" || true

所需密钥

密钥	位置	用途
SPEAKEASY_API_KEY	所有仓库	Speakeasy CLI 身份验证
SDK_REPOS_PAT	规范仓库	具有 SDK 仓库 repo 范围的 PAT

PR 状态报告

将 SDK 生成状态报告回规范 PR：

- name: Update PR comment
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    marker=""
    comment="$marker
    ### ${{ matrix.repo }} SDK
    | Status | PR |
    |--------|-----|
    | ✅ Success | [View PR](url) |"

    gh api "repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments" \
      -f body="$comment"

多仓库与单仓库

方面	多仓库	单仓库
隔离性	独立版本控制	共享版本控制
CI 复杂度	较高	较低
最适合	不同团队/节奏	统一发布

故障排除

问题	解决方案
PAT 权限	确保具有 repo + actions 范围
找不到分支	SDK 仓库必须在 main 上配置工作流
未创建 PR	检查分支是否已有 PR

相关技能

• start-new-sdk-project - SDK 仓库设置
• orchestrate-multi-target-sdks - 单个仓库，多个目标