Fix Broken Links

Fix Broken Links

You are fixing the broken links found by the daily link checker (scripts/link-checker/check-links.js, run against https://www.pulumi.com). Work through every reported link, pick the right strategy for each, open one auditable PR, and file issues for anything that can't be fixed in this repo.

Input

Read .broken-links.json from the repo root. Shape:

{
  "generated": "2026-06-02T15:00:00.000Z",
  "internal": [
    { "source": "...", "destination": "...", "reason": "HTTP_404", "hits": 210 },
    { "source": "(server logs)", "destination": "...", "reason": "REAL_404", "hits": 94 }
  ],
  "external": [{ "source": "...", "destination": "...", "reason": "HTTP_404" }]
}

• source — the live page the broken link was found on.
• destination — the URL that failed.
• reason — BLC reason code (HTTP_404, HTTP_410, ERRNO_ENOTFOUND, …), or

REAL_404 for entries merged from server logs (below).

• internal — destination is on pulumi.com; external — third-party.
• hits — optional: real 404 requests on that destination from server logs

over the export window (merged in by

scripts/link-checker/merge-404-signal.py). The list is sorted by hits

descending — work highest-hits first; entries without hits follow.

If both lists are empty, do nothing (the workflow won't invoke you in that case, but be defensive).

Real-404 signal (reason: "REAL_404")

These entries come from server logs, not the crawler: URLs readers actually

requested that returned 404 — external referrers, bookmarks, stale search

results. That means:

• source is (server logs) — there is no on-site page to edit; the fix is

almost always a Hugo alias or S3 redirect to the obvious successor

page, or the nearest section index when none exists.

• Verify the URL still 404s before fixing (the export is up to a week old; it

may have been fixed since).

• Residual noise the export's bot filter missed (crawler probes, exploit

scans) goes under False positives / not actioned — never give junk paths

a redirect.

Verify each link before fixing it

The checker produces false positives — never fix a link without confirming it's actually broken. The crawler hits live URLs with a bot user agent, so it routinely mis-flags links that are fine in a browser: bot-protected sites, transient 5xx/timeouts, rate-limiting, auth walls, and pages that block automated clients. excludeAcceptable() already filters the common transient reasons, but plenty slip through — especially in the external list.

For every reported link, confirm it's genuinely broken before touching anything:

• Re-check the destination — WebFetch (or curl -sIL) the URL. If it resolves, it's a false positive.
• Weigh the reason code. Internal HTTP_404/HTTP_410 on a pulumi.com path is almost always real. External failures, and codes like HTTP_403, HTTP_401, HTTP_429, HTTP_503, or connection/timeout errors, are frequently bot protection or transient — treat as suspect until confirmed.
• If it's a false positive, do not edit, redirect, or exclude it. Leave the link as-is and record it in the PR audit trail under a False positives / not actioned section, with the URL, the reason code, and one line on why it's fine (e.g. "resolves in browser; 403 is Cloudflare bot protection"). Optionally suggest it as a future exclusion-list candidate, but don't add it unless it's a recurring offender.

Only links you've confirmed broken proceed to triage below.

Skip links already being handled (deduplication)

Broken links persist for days, so the same ones surface in consecutive runs while

a fix is already in flight. **Before actioning a confirmed-broken link, check

whether it's already covered** — never open a second PR for a fix that's pending,

or file a duplicate issue.

For each confirmed-broken link, search for prior work:

• Open PRs in pulumi/docs. List candidates with

gh pr list --state open --search "broken link" --json number,title,url,headRefName

(prior runs use the fix/broken-links-* branch pattern). For a likely match,

confirm with gh pr view <n> / gh pr diff <n> that it actually covers this

link (same destination URL, source file, redirect, or exclusion entry).

• Existing issues, before filing a new one. For an out-of-scope item that

would become an issue in another repo, search that repo first —

gh issue list --repo pulumi/<repo> --state open --search "<url-or-path>"

(or gh search issues). If an open issue already tracks it, treat it as a

duplicate and reuse that issue's link; do not file another.

Classify each confirmed-broken link as actionable (no existing PR/issue

covers it) or duplicate (one does — capture the PR/issue URL). Then:

• All duplicates (every confirmed-broken link is already covered): do not

create a branch, PR, or any issue. Write a Slack summary to

.broken-links-pr.txt saying so and listing each link with its existing

PR/issue link, e.g. :link: 5 broken links — all already tracked (no new PR): <url> → #19470, …. Stop here.

• Some actionable, some duplicates: action only the non-duplicates (open the

PR, file new issues). Omit duplicates from the fixes, but list them in a

short Already tracked section in the PR description (one line each, linking

the existing PR/issue). Don't re-file or re-fix them.

Mapping a live URL back to its source file

source and destination are live https://www.pulumi.com/... URLs. To edit or redirect them you must find the file that produces them:

• Strip the origin to get the path, e.g. /docs/iac/concepts/stacks/.
• Hugo content lives under content/. A path like /docs/iac/concepts/stacks/ is produced by content/docs/iac/concepts/stacks/_index.md or .../stacks.md. Use Glob/Grep under content/ to locate it.
• To find *which* file emits a broken destination link, Grep for the link text under content/, data/, layouts/, and static/ — it may come from a data file, a shortcode, or a template, not prose.
• Registry, API-docs, and other generated paths have no source file in this repo (see "Out of scope" below).

Per-link triage

Apply the first row that matches.

| Situation | Strategy | Mechanism |

|---|---|---|

| Internal link points at a moved/renamed path, but the destination page still exists at a new path | Hugo alias | Add the old path to aliases: on the destination page's frontmatter |

| Internal link to a page that was deleted/restructured, or a non-Hugo path (registry, generated docs) | S3 redirect | Add a redirect line to the topic-appropriate file in scripts/redirects/ |

| Broken link living in editable content (content/docs, content/product, content/tutorials) | Edit at source | Fix the link in place; use the full root-relative path (/docs/...), never ../ |

| Broken link in a blog post and an equivalent replacement exists (same content, or close enough that the post's meaning is unchanged) | Edit at source + stamp lastmod | Swap the link; add/update lastmod: in that post's frontmatter (leave date: alone) |

| Broken link in a blog post with no equivalent replacement | Route around the prose | Add an alias/redirect so it resolves; if it's a dead external link, add it to the exclusion list. Do not reword blog prose |

| Dead / transient / bot-protected external link | Exclusion list | Add the URL to getDefaultExcludedKeywords() in check-links.js with an inline // comment naming the reason + blog post/issue. If the page mattered, prefer swapping to a Wayback snapshot |

| Redirect loop or malformed alias YAML | Repair | Remove the stale redirect / fix the alias indentation |

| Breakage owned by another repo (e.g. registry logoUrl, generated SDK docs) or otherwise unfixable here | Out of scope | File a GitHub issue and document it in the PR description — do not hack around it |

Mechanics

Hugo alias. Add the old path under aliases: in the destination page's frontmatter (root-relative, trailing slash):

aliases:
- /docs/old/path/

Full mechanics and edge cases: move-doc:references:alias-injection.

S3 redirect. Append one line to the topic-appropriate file in scripts/redirects/ (e.g. cicd-redirects.txt, iac-cli-redirects.txt, general-broken-links-redirects.txt when nothing more specific fits). Format is source-path|destination-url, one per line. The source is the path without a leading slash and usually ends in /index.html; the destination is root-relative (/docs/.../) or a full URL for off-site targets:

docs/old/path/index.html|/docs/iac/new/path/

Edit at source. Replace the broken link with the correct one. Internal docs links use the full canonical root-relative path (/docs/iac/concepts/stacks/); never ../. This is the only strategy that touches prose, and for blog posts it's limited to equivalent-content link swaps.

Blog lastmod. Any blog edit must add or update lastmod: (ISO date, today) in that post's frontmatter so the change is reflected, while the original date:/publish date stays put so post ordering doesn't shift.

Exclusion list. Add the URL to the array returned by getDefaultExcludedKeywords() in scripts/link-checker/check-links.js, grouped with similar entries, with an inline comment naming the reason and the post/issue, matching the existing style:

"https://example.com/gone",  // blog/<post>: 404, no replacement (#<issue>)

Editing guardrails

• Tutorials are editable like docs — fix their links at the source.
• Blog prose is editable only to substitute a broken link for an equivalent-content replacement, and every such edit stamps lastmod. Blog links with no equivalent replacement are routed around with an alias/redirect/exclusion, never reworded.
• Internal links use full root-relative paths, never ../.
• make lint and make build must both pass before you open the PR.

Output

If every confirmed-broken link is a duplicate (see deduplication above), skip

all of the below: open no branch, PR, or issue, write the "all already tracked"

Slack summary to .broken-links-pr.txt, and stop. Otherwise, for the actionable

(non-duplicate) links:

• Create a branch fix/broken-links-<date> (date from the workflow, e.g. fix/broken-links-2026-06-02).
• Make the fixes, grouping related changes into clear commits.
• File a GitHub issue (gh issue create) for every new out-of-scope item (reuse the existing issue for duplicates).
• Run make lint and make build; fix anything they surface.
• Open a ready (non-draft) PR to master.
• Write the final PR URL plus a one-line summary to .broken-links-pr.txt for the workflow's Slack step, e.g.:

:link: Fixed 7 broken links — <PR URL> (2 aliases, 1 redirect, 3 source edits, 1 issue filed)

PR description contract (auditability)

The reviewer must be able to audit every decision without re-deriving it. Model the description on PR #19469. Include:

• A table or list of every broken link → the strategy applied → one line of non-obvious reasoning (why a redirect vs. an alias, why excluded, etc.).
• A Verification section: confirm make lint and make build passed, and note that each link was re-checked before fixing.
• A False positives / not actioned section listing every reported link you confirmed was actually fine, with its reason code and why (so the reviewer knows it was checked, not missed).
• An Already tracked section, when any link was skipped as a duplicate: one succinct line per link linking the existing PR or issue that covers it.
• An Out of scope / filed issues section linking every issue you created for breakage owned by other repos or otherwise unfixable here.