Skip to content

ci(preview-checks): resolve preview URL from the deployment check-run and check API pages against the PR head - #805

Merged
hlenke merged 2 commits into
mainfrom
hannes/preview-checks-url-and-head-nav
Nov 8, 2026
Merged

hlenke merged 2 commits into
mainfrom
hannes/preview-checks-url-and-head-nav

Conversation

@hlenke

@hlenke hlenke commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Affected Components

  • Content & Marketing
  • Pricing
  • Test
  • Docs
  • Learn
  • Other (CI: preview-checks workflow)

Fixes two false failures in Preview checks. Each fix is its own commit.

1. "Resolve preview URL" times out when Mintlify posts a duplicate preview comment

Mintlify sometimes posts a second mintlify-preview-comment comment and keeps updating the first one. The step picked the newest comment by creation time (| last), so it polled a comment frozen at 🟡 Building until the ~21-minute timeout. This failed 5 runs on #446, #610 and #669. 13 PRs have such a duplicate.

  • On success, take the preview URL from the Mintlify Deployment check-run for $HEAD_SHA. Its output.summary names the preview it built, so the comment isn't needed.
  • The comment fallback (used when the site didn't change) now reads all pages of comments (--paginate --slurp; it used to read only the first 30) and takes max_by(.updated_at). The comment body has no SHA to match on.

2. API page check expects pages the preview can't have

check-api-preview.mjs read docs.json from the merge commit (refs/pull/N/merge), but Mintlify builds the preview from the PR head. Branches older than c7282f8 (Oct 6) therefore failed with 404s on the 5 api-reference/usage/* pages that only exist on main. This hit #449, #475, #506 and #511.

  • The Verify step adds a worktree of the head commit and passes it as a new optional second argument (the docs root to read the nav from). The script still runs from the merge checkout, because older heads don't have it.

Not fixed here: the 23 status-page 404s right after a long-lived branch first merges c7282f8. Mintlify serves stale routes on the first preview build after pages switch from MDX to OpenAPI-generated pages at the same URLs, and the next build is fine. That's on Mintlify's side; no open PR is affected today.

Notes for the Reviewer

I ran the edited step scripts locally against real PRs (main's timeout cut to 45s):

PR / head Path This branch main
#446 64a3f6f0 check-run URL found at once timed out
#610 b17c8c49 comment fallback live comment's URL timed out
#669 3497899f comment fallback live comment's URL timed out
#804 d430018e check-run same URL same URL

Verify step, run as written against the live #804 preview:

actionlint is clean on both commits, and node --test .github/scripts/*.test.mjs passes (15/15).

Neither fix has run in Actions yet. This PR only touches .github/, so Mintlify will likely skip its deployment, and this PR's own run will then skip the preview checks without testing either fix. The first docs PR after merge will run the check-run path (step log: Mintlify Deployment success — preview: …) and the new Verify step.

🤖 Generated with Claude Code

hlenke and others added 2 commits November 7, 2026 20:34
…-run

Mintlify sometimes posts a second preview comment and keeps updating the
first one. Picking the newest comment by creation time then polled a frozen
"Building" comment until the step timed out (#446, #610, #669).

Take the URL from the Mintlify Deployment check-run for the head commit,
which names the preview it built. The comment fallback, still used when the
site didn't change, now pages through all comments and takes the most
recently updated one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e ref

Mintlify builds the preview from the PR head, but the API page check read
docs.json from the merge commit. A branch older than a generated API page
on main then failed with 404s for pages it never had (the 5 usage pages
on #449, #475, #506, #511).

Read the expected pages from a worktree of the head commit. The script
still runs from the merge checkout, since older heads don't have it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Nov 8, 2026, 1:41 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

@hlenke
hlenke merged commit e0e0277 into main Nov 8, 2026
7 checks passed
@hlenke
hlenke deleted the hannes/preview-checks-url-and-head-nav branch November 8, 2026 01:42

This branch was successfully deployed

1 active deployment
staging — 8ae32662 Deployed Nov 8, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant