ci(release): gate production docs on stable release success#2989
Merged
Conversation
Mintlify currently deploys from main, so docs ship as soon as a doc commit lands, often weeks before the underlying packages reach npm via the weekly stable release. Move production docs onto a `docs-stable` branch that the release workflow only advances after every publish step succeeds, so docs and packages move together. - release-stable.yml pushes stable -> docs-stable as its final step, only reachable on full success - new preview-stable-docs.yml triggers a Mintlify preview for any PR targeting stable so the promote-stable PR shows reviewers the exact docs that will go live - requires manual setup before this can take effect: create the docs-stable branch from current stable, switch Mintlify's deployment branch in the dashboard, and add MINTLIFY_API_KEY / MINTLIFY_PROJECT_ID repo secrets (preview workflow no-ops without them)
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59362acfd3
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Address review on PR 2989. Two issues: - The promote step refetched `origin/stable` and pushed it, so a newer commit landing on stable while the release was still publishing would be promoted to docs-stable before the next run actually published it. The orchestrator now emits `promote_sha` (current HEAD) only when no package failed and no deferral happened; the workflow gates the push on that output and pushes the explicit SHA instead of refetching. - The preview workflow called `gh pr comment` without checking out the repo, so gh had no repo context. Added `--repo "$GITHUB_REPOSITORY"`.
This was referenced Apr 29, 2026
caio-pizzol
added a commit
that referenced
this pull request
Apr 29, 2026
* ci(release): gate production docs on stable release success Mintlify currently deploys from main, so docs ship as soon as a doc commit lands, often weeks before the underlying packages reach npm via the weekly stable release. Move production docs onto a `docs-stable` branch that the release workflow only advances after every publish step succeeds, so docs and packages move together. - release-stable.yml pushes stable -> docs-stable as its final step, only reachable on full success - new preview-stable-docs.yml triggers a Mintlify preview for any PR targeting stable so the promote-stable PR shows reviewers the exact docs that will go live - requires manual setup before this can take effect: create the docs-stable branch from current stable, switch Mintlify's deployment branch in the dashboard, and add MINTLIFY_API_KEY / MINTLIFY_PROJECT_ID repo secrets (preview workflow no-ops without them) * fix(release): gate docs-stable promote on verified release SHA Address review on PR 2989. Two issues: - The promote step refetched `origin/stable` and pushed it, so a newer commit landing on stable while the release was still publishing would be promoted to docs-stable before the next run actually published it. The orchestrator now emits `promote_sha` (current HEAD) only when no package failed and no deferral happened; the workflow gates the push on that output and pushes the explicit SHA instead of refetching. - The preview workflow called `gh pr comment` without checking out the repo, so gh had no repo context. Added `--repo "$GITHUB_REPOSITORY"`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mintlify currently deploys from
main, so docs ship as soon as a doc commit lands, often weeks before the underlying packages reach npm via the weekly stable release. This change moves production docs onto adocs-stablebranch that the release workflow only advances after every publish step succeeds, so docs and packages move together.release-stable.ymlpushesstabletodocs-stableas its final step. Because it sits after all semantic-release and PyPI publish steps in a single sequential job, any earlier failure aborts the workflow and the docs branch stays put.preview-stable-docs.ymltriggers a Mintlify preview for any PR targetingstable. Promote-stable PRs no longer target the deployment branch under this design, so Mintlify's automatic preview won't fire for them; this workflow restores that review checkpoint by calling the preview API and commenting the URL on PR open.stabledirectly. Rejected because Mintlify reacts to the push (release candidate present) rather than to release success (packages actually on npm), so a failedrelease-stable.ymlrun would leave production docs describing packages users cannot install.Manual setup required before merging:
docs-stablebranch on origin:git push origin origin/stable:refs/heads/docs-stablemaintodocs-stableMINTLIFY_API_KEYandMINTLIFY_PROJECT_IDrepo secrets (preview workflow no-ops without them, so this can be deferred without breaking anything)docs-stablegets branch protection, allow the GitHub App used byrelease-stable.ymlto push to it