From 09aee8c2374db2d3cb63063a12b40243e9788153 Mon Sep 17 00:00:00 2001 From: miliberlin Date: Tue, 26 May 2026 19:14:13 +0200 Subject: [PATCH 1/3] ci: label preview-checks Checkly test sessions by PR number Pass --test-session-name to `checkly test --record` so each PR's preview-checks run shows up in Checkly's test sessions list with a recognizable label instead of a generic timestamped row. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/preview-checks.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/preview-checks.yml b/.github/workflows/preview-checks.yml index 88f62594..a62c14ad 100644 --- a/.github/workflows/preview-checks.yml +++ b/.github/workflows/preview-checks.yml @@ -107,10 +107,12 @@ jobs: CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }} SLACK_OPS_WEBHOOK_URL: ${{ secrets.SLACK_OPS_WEBHOOK_URL }} DOCS_BASE_URL: ${{ steps.preview.outputs.url }} + PR_NUMBER: ${{ github.event.pull_request.number }} run: | npx checkly test \ --env "DOCS_BASE_URL=$DOCS_BASE_URL" \ --record \ + --test-session-name="Checkly Docs preview — PR #$PR_NUMBER" \ --reporter=github \ --timeout=1200 From a706a06a992b7a05cc989441edbb9577c5ae741d Mon Sep 17 00:00:00 2001 From: miliberlin Date: Tue, 26 May 2026 19:20:42 +0200 Subject: [PATCH 2/3] ci: short-circuit docs-gate and preview-checks when Mintlify Deployment is skipped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mintlify sometimes returns `conclusion: skipped` on its Deployment check — when that happens the dependent link-rot and vale-spellcheck validations are never posted, and no preview URL is published. Both workflows used to wait the full 30/20-minute timeout on these no-op PRs. Detect the skip via the Mintlify Deployment check-run and exit successfully: - docs-gate: skips the wait loop entirely when the latest Mintlify Deployment is completed with conclusion `skipped`. - preview-checks: emits `skipped=true` from the wait step and gates the Node setup, install, test run, and report publish on it. Also tidy up the preview-checks Checkly test invocation while we're in here: rename the test session to plain "Checkly docs" and pass the PR number via CHECKLY_TEST_ENVIRONMENT (e.g. `preview-pr-344`) so sessions are discoverable by PR in the Checkly UI. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/docs-gate.yml | 16 ++++++++++++++++ .github/workflows/preview-checks.yml | 28 ++++++++++++++++++++++------ 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs-gate.yml b/.github/workflows/docs-gate.yml index 8ea6e8e3..23741cf1 100644 --- a/.github/workflows/docs-gate.yml +++ b/.github/workflows/docs-gate.yml @@ -74,6 +74,22 @@ jobs: for attempt in $(seq 1 $MAX_ATTEMPTS); do CHECKS=$(gh api "repos/${{ github.repository }}/commits/$HEAD_SHA/check-runs" --paginate) + # Short-circuit: if the Mintlify Deployment was skipped (e.g. + # Mintlify decided the change is a no-op), the dependent + # link-rot and vale-spellcheck checks never get posted. Exit + # successfully rather than time out waiting for them. + DEPLOY_CONCLUSION=$(echo "$CHECKS" | jq -r ' + [.check_runs[] | select(.name == "Mintlify Deployment")] + | sort_by(.started_at) | reverse | .[0] + | if . == null or .status != "completed" then "" + else .conclusion // "" + end + ') + if [ "$DEPLOY_CONCLUSION" = "skipped" ]; then + echo "Mintlify Deployment was skipped — no preview to validate. Exiting successfully." + exit 0 + fi + ALL_DONE=true FAILED="" diff --git a/.github/workflows/preview-checks.yml b/.github/workflows/preview-checks.yml index a62c14ad..e9938241 100644 --- a/.github/workflows/preview-checks.yml +++ b/.github/workflows/preview-checks.yml @@ -51,12 +51,28 @@ jobs: env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} run: | set -euo pipefail MAX_ATTEMPTS=40 # 40 * 30s = 20 min SLEEP=30 for attempt in $(seq 1 $MAX_ATTEMPTS); do + # Short-circuit: if Mintlify Deployment was skipped, no preview + # URL will ever appear. Skip the Checkly test run cleanly. + DEPLOY_CONCLUSION=$(gh api "repos/${{ github.repository }}/commits/$HEAD_SHA/check-runs" --paginate --jq ' + [.check_runs[] | select(.name == "Mintlify Deployment")] + | sort_by(.started_at) | reverse | .[0] + | if . == null or .status != "completed" then "" + else .conclusion // "" + end + ') + if [ "$DEPLOY_CONCLUSION" = "skipped" ]; then + echo "Mintlify Deployment was skipped — no preview to test." + echo "skipped=true" >> "$GITHUB_OUTPUT" + exit 0 + fi + COMMENT_BODY=$(gh api "repos/${{ github.repository }}/issues/$PR_NUMBER/comments" \ --jq '[.[] | select(.user.login == "mintlify[bot]" and (.body | contains("mintlify-preview-comment")))] | last | .body // empty') @@ -90,32 +106,32 @@ jobs: exit 1 - name: Set up Node - if: steps.detect.outputs.docs_changed == 'true' + if: steps.detect.outputs.docs_changed == 'true' && steps.preview.outputs.skipped != 'true' uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' - name: Install dependencies - if: steps.detect.outputs.docs_changed == 'true' + if: steps.detect.outputs.docs_changed == 'true' && steps.preview.outputs.skipped != 'true' run: npm ci - name: Run Checkly checks against preview - if: steps.detect.outputs.docs_changed == 'true' + if: steps.detect.outputs.docs_changed == 'true' && steps.preview.outputs.skipped != 'true' env: CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }} CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }} SLACK_OPS_WEBHOOK_URL: ${{ secrets.SLACK_OPS_WEBHOOK_URL }} DOCS_BASE_URL: ${{ steps.preview.outputs.url }} - PR_NUMBER: ${{ github.event.pull_request.number }} + CHECKLY_TEST_ENVIRONMENT: preview-pr-${{ github.event.pull_request.number }} run: | npx checkly test \ --env "DOCS_BASE_URL=$DOCS_BASE_URL" \ --record \ - --test-session-name="Checkly Docs preview — PR #$PR_NUMBER" \ + --test-session-name="Checkly docs" \ --reporter=github \ --timeout=1200 - name: Publish Checkly report to step summary - if: always() && steps.detect.outputs.docs_changed == 'true' + if: always() && steps.detect.outputs.docs_changed == 'true' && steps.preview.outputs.skipped != 'true' run: cat checkly-github-report.md >> "$GITHUB_STEP_SUMMARY" || true From 2be3beb1f7b982095c5545bdfd3f0f9253cd2406 Mon Sep 17 00:00:00 2001 From: miliberlin Date: Tue, 26 May 2026 19:24:58 +0200 Subject: [PATCH 3/3] ci: skip runner spin-up on non-docs PRs Two small wins on PRs that touch only the bits Mintlify doesn't render (workflow files, __checks__/, scripts, root-level *.md, etc.): - preview-checks: add paths-ignore so the runner doesn't start at all when every changed path matches the ignore list. The in-workflow detect step stays as a fine-grained backstop for mixed docs/non-docs PRs. - static-docs-checks: reorder steps so detect runs first, then gate Set up Node and npm ci on `openapi_changed || docs_changed`. Workflow still always reports a status (required check), but skips ~15-30s of install work when neither inner step will run. Net effect: ~25-45s of runner time saved on every non-docs PR. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/preview-checks.yml | 14 ++++++++++++++ .github/workflows/static-docs-checks.yml | 20 +++++++++++--------- 2 files changed, 25 insertions(+), 9 deletions(-) diff --git a/.github/workflows/preview-checks.yml b/.github/workflows/preview-checks.yml index e9938241..223e6987 100644 --- a/.github/workflows/preview-checks.yml +++ b/.github/workflows/preview-checks.yml @@ -3,11 +3,25 @@ name: Preview checks # Runs the Checkly synthetic checks against the Mintlify PR preview URL. # Skips silently when a PR touches no docs files. Fails when the Mintlify # preview itself failed (no URL to target). +# +# `paths-ignore` keeps the runner from spinning up at all on non-docs PRs. +# The in-workflow detection below is the fine-grained backstop for the +# rare case where a PR mixes docs and non-docs paths. on: pull_request: branches: [main] types: [opened, synchronize, reopened, ready_for_review] + paths-ignore: + - '.github/**' + - '**/*.sh' + - '*.md' + - 'package.json' + - 'package-lock.json' + - 'node_modules/**' + - 'checkly.config.ts' + - 'block-headless.js' + - '__checks__/**' concurrency: group: preview-checks-${{ github.event.pull_request.number }} diff --git a/.github/workflows/static-docs-checks.yml b/.github/workflows/static-docs-checks.yml index cc701352..a8aadfe8 100644 --- a/.github/workflows/static-docs-checks.yml +++ b/.github/workflows/static-docs-checks.yml @@ -29,15 +29,6 @@ jobs: with: fetch-depth: 0 - - name: Set up Node - uses: actions/setup-node@v4 - with: - node-version: '20' - cache: 'npm' - - - name: Install dependencies - run: npm ci - - name: Detect changed paths id: detect env: @@ -62,6 +53,17 @@ jobs: echo "docs_changed=false" >> "$GITHUB_OUTPUT" fi + - name: Set up Node + if: steps.detect.outputs.openapi_changed == 'true' || steps.detect.outputs.docs_changed == 'true' + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + if: steps.detect.outputs.openapi_changed == 'true' || steps.detect.outputs.docs_changed == 'true' + run: npm ci + - name: Validate OpenAPI spec if: steps.detect.outputs.openapi_changed == 'true' run: npx mint openapi-check api-reference/openapi.json