How to Coordinate a Release Across Multiple Repositories

A coordinated release uses one orchestrator workflow to tag and dispatch each repo release in order, so services ship as a set rather than drifting.

An orchestrator workflow (often in a manifest repo) loops over the release set, creates a tag in each repo, and dispatches its release workflow, optionally waiting between stages.

Steps

• List the repos and the version to release as workflow inputs.
• For each repo, create the release tag via the API.
• Dispatch the repo release workflow and, where ordering matters, wait before the next.

Orchestrator workflow

on:
  workflow_dispatch:
    inputs:
      version:
        type: string
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - env:
          GH_TOKEN: ${{ secrets.CROSS_REPO_PAT }}
        run: |
          for repo in api web worker; do
            gh api --method POST \
              /repos/my-org/$repo/git/refs \
              -f ref="refs/tags/${{ inputs.version }}" \
              -f sha="$(gh api /repos/my-org/$repo/git/refs/heads/main --jq .object.sha)"
          done

Gotchas

• Decide the failure policy up front: stop on the first failed repo, or continue and report at the end.
• Use the same version string in every repo so the release set is easy to reason about later.

Related guides