Run any Skill in Manus with one click

pages-ci-doctor

Stars16

Forks2

UpdatedJuly 3, 2026 at 12:28

Diagnose and un-stick GitHub Pages publishing for nf-metro when a PR render preview or the docs site isn't updating. Use when a `_pr/<N>/` preview 404s or shows stale content, the "render preview is ready" link doesn't work, the docs site didn't refresh after a merge, or you suspect a Pages build stalled. Trigger on phrases like "the preview isn't updating", "the render preview link is broken", "check the pages ci", "poke the pages build", "docs site is stale", "did my preview publish". Covers the legacy-builder stall (the usual culprit), the re-trigger fix, the pr-renders -> pr-render-publish -> build chain, the render content marker, and the CDN caching gotchas that make verification misleading.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

seqeralabs

seqeralabs/nf-metro

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

fix-issue

seqeralabs/nf-metro

End-to-end workflow for fixing GitHub issues on the nf-metro repo with diagnostic rigor. Use when the user references a GitHub issue (by number, URL, or description) and wants it fixed. Handles worktree setup, a reused persistent env (no per-issue env creation), diagnostic-first investigation, authoring-mistake-vs-engine-bug triage (never dodge an engine bug by doctoring the reproducer), invariant-test-first implementation, runtime validators, evidence-cited fix verification, /simplify pass, full-repo lint, visual review via render preview, narrow-the-fix iteration on regressions, cost discipline (targeted tests, CI render-diff over local gallery rebuilds, skip-ci on WIP), scope discipline that fixes adjacent fallout in-session via delegated subagents instead of deferring it to a child issue, standalone issue-body hygiene, additive-only PR hygiene (no force-push, no narrative comments), clean execution of an authorised admin-merge (preserve history, no CI re-run), origin verification after every push, and PR

2026-07-2316

release

seqeralabs/nf-metro

End-to-end release workflow for nf-metro. Checks the bioconda recipe for missing deps and bumps its build number if needed, bumps version in pyproject.toml and __init__.py, drafts a docs/releases/<version>.md page from the git log since the last tag (with illustrations where relevant), wires it into mkdocs.yml nav and the releases index table, then opens a PR. After merge, reminds you to create the GitHub Release. Trigger on phrases like "cut a release", "release X.Y.Z", "prepare release", "bump version to X.Y.Z".

2026-07-0116

nf-metro-gate-triage

seqeralabs/nf-metro

Run a routing gate-arm triage slice on nf-metro - give every un-exercised branch arm in a layout/routing module a verdict (reachable -> author a fixture, defensive, candidate-dead, or reachable-but-defective -> file a bug). Use when the user wants to triage routing gate arms, close coverage-matrix gaps, work a

2026-06-2916

pipeline-metro-setup

seqeralabs/nf-metro

Wire an nf-metro diagram into an nf-core (or any Nextflow) pipeline repo - the mechanical pipeline-side setup, not the authoring of the .mmd itself. Use whenever the user wants to add nf-metro tooling to a pipeline (assets/metro_map.mmd, docs/dev/metro_map.md, the rendered SVG/PNG/animated assets, README image swap, CHANGELOG entry), replace an existing workflow.png/svg with a metro map, mirror the nf-core/rnaseq setup on a new pipeline, or pin nf-metro to a named branch of a fork while waiting for upstream fixes to land. Trigger on phrases like "set up nf-metro on pipeline X", "wire the metro map into the repo", "replace workflow.png with a metro map", "ship the metro diagram in pipeline Y", "pin nf-metro to my fork branch while we wait for the fixes", "what assets do I need in docs/images for the metro map".

2026-06-2916

render-topologies

seqeralabs/nf-metro

Local visual regression check for layout or rendering changes. Renders all gallery examples, pixel-diffs against main, and opens changed renders as BEFORE/AFTER pairs. In most cases the CI render preview on a PR is sufficient - use this skill only for pre-push confidence on risky changes or when the user explicitly asks for a local diff.

2026-06-2916

serve-docs

seqeralabs/nf-metro

Spin up the Astro / Starlight documentation site locally for live preview, optionally for a specific nf-metro branch. Use when the user wants to run, serve, preview, or develop the docs site (website/) - phrases like "serve the docs", "spin up the site", "run the docs locally", "preview the website", "start the astro server", "preview the docs for branch X / this PR", or when iterating on docs content, theme/layout overrides, or the gallery/pipelines/playground pages and wanting to see changes in a browser. Wraps scripts/serve_docs.sh, which generates the git-ignored dynamic content (gallery, pipelines, playground manifest) before starting the dev server, and with --branch checks the branch out into an isolated worktree and installs its nf_metro so the renders reflect that branch.

2026-06-2716

name	pages-ci-doctor
description	Diagnose and un-stick GitHub Pages publishing for nf-metro when a PR render preview or the docs site isn't updating. Use when a `_pr/<N>/` preview 404s or shows stale content, the "render preview is ready" link doesn't work, the docs site didn't refresh after a merge, or you suspect a Pages build stalled. Trigger on phrases like "the preview isn't updating", "the render preview link is broken", "check the pages ci", "poke the pages build", "docs site is stale", "did my preview publish". Covers the legacy-builder stall (the usual culprit), the re-trigger fix, the pr-renders -> pr-render-publish -> build chain, the render content marker, and the CDN caching gotchas that make verification misleading.
allowed-tools	Bash(gh ), Bash(git ), Bash(curl *)

Pages CI doctor

Diagnose why an nf-metro PR render preview (or the docs site) isn't showing up, and apply the known fix. The usual culprit is a stalled GitHub Pages build, not the workflows.

Constants

Repo: seqeralabs/nf-metro. Owner/site: https://seqeralabs.github.io/nf-metro/.
Preview URL for PR N: https://seqeralabs.github.io/nf-metro/_pr/<N>/.
Pages source is build_type: legacy (branch builder serving gh-pages). Actions-source (build_type: workflow) was tried and reverted: it can't publish this repo's accumulate-into-one-branch model (every deploy shares main's commit SHA, so new content silently isn't served). Do not switch back to workflow.
A healthy legacy build completes in ~40-140s. A build sitting in status: building for several minutes is stalled - the recurring failure mode (likely a flaky Pages backend from the pinin4fjords -> seqeralabs transfer; not fixable from CI).

How publishing works (the chain)

PR push -> "PR render preview" (pr-renders.yml, on: pull_request)
         -> "Publish render preview" (pr-render-publish.yml, on: workflow_run)
              pushes _pr/<N>/ to the gh-pages branch (peaceiris)
         -> GitHub legacy Pages build (async, per gh-pages push)  <- STALLS HERE
         -> live at _pr/<N>/

Merges to main go through "Deploy docs" (docs.yml) into gh-pages, same build step. A push to gh-pages only updates the branch; the build is what makes it live.

Verification gotcha - read before curling

GitHub Pages/Fastly caches responses including 404s, and ?query cache-busting is unreliable (the cache key sometimes ignores the query string). So a 200/404 you see may be stale.

To read true origin, request a path you have not requested this session. The cleanest: the no-trailing-slash form _pr/<N> -> a 301 to _pr/<N>/ means the dir exists at origin; a 404 means it doesn't.
Trust x-cache: MISS + age: 0. Distrust x-cache: HIT (stale).
The diff page carries <meta name="nf-metro-render-run" content="<run-id>">. Content is genuinely current when that marker equals the pr-renders run id that produced it (the publisher gates the "ready" comment on this).

Step 1 - identify the PR and its head

PR=<number>
gh pr view $PR --repo seqeralabs/nf-metro --json headRefName,headRefOid,state \
  --jq '{branch:.headRefName, head:.headRefOid[:9], state}'

Step 2 - did the render chain run?

BR=<branch-from-step-1>
gh run list --repo seqeralabs/nf-metro --branch "$BR" --limit 5 \
  --json name,event,status,conclusion,headSha,createdAt \
  --jq '.[] | "[\(.name)] \(.event) \(.status)/\(.conclusion) \(.headSha[:9]) \(.createdAt)"'
gh run list --repo seqeralabs/nf-metro --workflow pr-render-publish.yml --limit 5 \
  --json databaseId,status,conclusion,createdAt \
  --jq '.[] | "\(.databaseId) \(.status)/\(.conclusion) \(.createdAt)"'

No "PR render preview" run on the head SHA -> the push didn't trigger it. Check the last commit for a [skip ci] marker (it skips pull_request too).
"PR render preview" ran but no matching "Publish render preview" -> the workflow_run chain didn't fire, or the render found no changes.

Step 3 - did the content reach the branch?

git fetch origin gh-pages --quiet
git log origin/gh-pages -1 --format='%cI %s' -- _pr/$PR/    # when _pr/<N> last changed
git ls-tree origin/gh-pages _pr/$PR/ --name-only | head     # index.html present?

If _pr/<N>/index.html is on the branch but the URL is stale, the branch is fine and the build is the problem -> Step 4.

Step 4 - is the build stalled? (the usual answer)

gh api repos/seqeralabs/nf-metro/pages/builds/latest \
  --jq '"status=\(.status) created=\(.created_at) commit=\(.commit[:9]) dur=\(.duration) err=\(.error.message)"'
gh api "repos/seqeralabs/nf-metro/pages/builds?per_page=5" \
  --jq '.[] | "\(.created_at) \(.status) \(.commit[:9]) dur=\(.duration)"'

status: building for more than ~3 min (compare against the ~40-140s of past built entries) = stalled.
status: errored = failed.
Either way -> Step 5.

Step 5 - poke it (the fix)

Re-trigger the branch build, then poll to completion:

gh api -X POST repos/seqeralabs/nf-metro/pages/builds --jq '.status'
for i in $(seq 1 15); do
  st=$(gh api repos/seqeralabs/nf-metro/pages/builds/latest --jq '.status')
  echo "$(date -u +%H:%M:%SZ) $st"
  [ "$st" = "built" ] && break
  [ "$st" = "errored" ] && { echo "errored"; break; }
  sleep 20
done

A single re-trigger usually clears it (builds in ~40-140s). If the re-triggered build also stalls, re-trigger again - it can take two. If it keeps stalling across several tries, it's a live GitHub incident (check https://www.githubstatus.com/); wait it out, the branch content is safe.

Step 6 - confirm it's genuinely live

Use a true-origin probe (Step 0 gotcha):

# dir exists at origin? (never-requested no-slash form -> 301 if live)
curl -sS -o /dev/null -w "_pr/$PR -> HTTP %{http_code} loc=%header{location} x-cache=%header{x-cache}\n" \
  "https://seqeralabs.github.io/nf-metro/_pr/$PR"
# and the freshest content, checking the marker matches the pr-renders run id
body=$(curl -sS "https://seqeralabs.github.io/nf-metro/_pr/$PR/index.html?cb=$(date +%s%N)")
printf '%s' "$body" | grep -oiE "Generated[^<]*|[0-9]+ changed out of [0-9]+"
printf '%s' "$body" | grep -o '<meta name="nf-metro-render-run" content="[^"]*">'

Compare the marker's run id to the latest "PR render preview" run id from Step 2; equal means the served page is the current render.

Where's the break? (quick table)

Symptom	Likely cause	Action
No "PR render preview" run	push skipped CI, or not a PR to `main`	re-push without `[skip ci]`
Render ran, no publish run	`workflow_run` miss / no render changes	check publish run logs; a no-change render is expected to skip publishing
`_pr/<N>` on branch, URL stale/404	build stalled	Step 5 re-trigger
Build `built`, URL still stale	CDN negative cache or old marker	true-origin probe (no-slash / marker); wait out the 404 cache TTL
Build keeps stalling across retries	GitHub Pages incident	check githubstatus.com, wait

Docs site (not a PR preview)

Same diagnosis, minus the PR steps: after a merge to main, "Deploy docs" pushes to gh-pages; if the site didn't refresh, it's Step 4/5 (build stalled -> poke).