cross-repo-release-preflight

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.