| name | cross-repo-release-preflight |
| description | Fail fast when a release workflow depends on credentials or access to a second repository. |
| domain | release-management |
| confidence | high |
| source | earned |
Context
Use this when a source repo release triggers a second workflow that clones, updates, or tags a separate published/distribution repo.
Patterns
- Add a dedicated preflight job before the first cross-repo checkout.
- Validate the required secret exists with an explicit error message naming the exact secret the maintainer must add.
- Validate target repo reachability with the same credential the workflow will use for checkout/push.
- Add a source-side sync gate so downstream publication runs only when the published/install surface changed since the previous release tag.
- Add a manual
workflow_dispatch path that can replay publication for an existing release tag without forcing a brand new source release.
- For cross-repo PAT auth, store the token as a repository secret and use it consistently for all checkout/push operations in the workflow.
- Alternatively, for GitHub App auth: keep the App ID in a repository variable, keep the private key in a repository secret, and mint a fresh installation token per job instead of sharing one long-lived token across the workflow.
- If the target repo owns the final commit, add defensive version guards there: reject explicit tag/version mismatches and reject downgrade syncs before overwriting the published surface.
- Let the duplicate guard distinguish automatic versus manual runs: automatic duplicates should skip cleanly, while manual runs should still be able to repair missing tags or re-sync the same version.
- Reflect the follow-on workflow in release docs and release verification checklists so maintainers confirm both workflows, not just the primary release.
Examples
publish-plugins.yml checks PLUGINS_REPO_TOKEN secret exists, then verifies access to sbroenne/mcp-server-excel-plugins before cloning it.docs/RELEASE-STRATEGY.md includes the follow-on plugin publish workflow in the release monitoring and verification steps.mcaps-microsoft/iq-core-dev uses a release-time sync gate so workflow-only/dev-only releases do not trigger downstream published-repo sync.mcaps-microsoft/iq-core rejects downgrade syncs and explicit tag/version mismatches before committing the copied plugin surface.publish-plugins.yml can expose workflow_dispatch with release_tag=vX.Y.Z so maintainers can replay the same published bundle path after a partial failure.
Anti-Patterns
- Letting the first
actions/checkout failure be the only signal that credentials are missing.
- Reusing a long-lived PAT or one shared app token across multiple jobs when each job can mint the minimal installation token it needs.
- Triggering cross-repo publication on every release even when nothing in the install surface changed.
- Accepting an explicit version/tag input without asserting it matches the incoming manifest version.
- Documenting only the primary release workflow when a second workflow performs the actual publication.
