ci: respect redirected pages in removed URL check

[rajannpatel]

Description

This PR updates the check-removed-urls.yml GitHub workflow to prevent false positives when a documentation page is intentionally removed or renamed, but a proper redirect has already been configured in docs/redirects.txt.

Previously, the workflow performed a strict text diff on the built HTML output. If a URL disappeared, the check failed immediately, completely unaware that a redirect existed.

Key Changes

• Added workflow_call Inputs: decoupled the base reference variables so this workflow can be cleanly reused by other pipelines.
• Path Normalization: Streamlined the find and sed pipeline to parse built HTML structures safely and output clean, predictable path formats.
• Redirect-Aware Validation: Replaced the Bash loop with an inline Python verification script. It parses docs/redirects.txt using the native csv module and checks all structural markdown possibilities (page.md, page/index.md, or directory-level paths) before flagging a URL as missing.

Testing Instructions

1. If a PR removes a page without adding it to docs/redirects.txt, the workflow should fail and list the unhandled URL.
2. If a PR removes a page and correctly logs the source path in docs/redirects.txt, the workflow should print a green checkmark (✅ Ignored) and pass successfully.

Checklist

• Tested changes against private/public fork contexts
• Handled empty lines and comment blocks inside redirects.txt
• Validated fallback behavior for reusable workflow triggers
• Have you updated CHANGELOG.md with relevant non-documentation file changes?
• Have you updated the documentation for this change?

[medubelko]

@SecondSkoll I think you were the principal author behind this script, so I'd like to defer this one to you.

[SecondSkoll]

Checked and validated against my own docs, works just fine.

Note: The old check was broken by the introduction of rerediraffe.

[medubelko]

@jahn-junior While this might not fit our ultimate goals for rerediraffe, this fixes a broken workflow. If the script were moved to an external file, would that be a satisfactory stop-gap?

[jahn-junior]

@medubelko

@jahn-junior While this might not fit our ultimate goals for rerediraffe, this fixes a broken workflow. If the script were moved to an external file, would that be a satisfactory stop-gap?

No complaints from me. I haven't had time to look at the Python in detail, but it seems simple enough.

[SecondSkoll]

Could you please move the Python script in the "Compare URLs" step to /docs/_dev/, and then then call it in the workflow?

[rajannpatel]

Could you please move the Python script in the "Compare URLs" step to /docs/_dev/, and then then call it in the workflow?

@SecondSkoll please let me know what you think?

Changes made

[SecondSkoll]

LGTM, @jahn-junior any final notes or are you happy to merge this in now?

[jahn-junior]

I'm happy with the overall shape of this. Just one question about the args in the Python script. Once we've settled that, I'll go ahead and merge.

[JordanMG13]

Regarding the PR I mentioned above, since they are very similar in function (mine adds some suggested redirects from a fuzzy search through the current docs dir), I'll wait for this one to get pulled in first 😄

[jahn-junior]

Tested a variety of pass and fail scenarios on my fork, and everything works as I'd expect it to. Once you update the changelog (and optionally take a look at my final comment), I'll merge this.

Thanks again for all of your work on this!

[swetha1654]

@jahn-junior @rajannpatel this PR is causing downstream repos that use the workflow to break. Is it expected now for all downstream repos to have the check_removed_urls python script? Or is this a bug in the workflow where it needs to checkout the same ref of canonical/sphinx-stack that contains the check_removed_urls script?

[rajannpatel]

I think this PR should resolve your issue: #624

[rajannpatel]

Before commit d57b2c9 <d57b2c9> the Python script was embedded directly inside check-removed-urls.yml, and the workflow had no dependencies on external files in the checked-out repository. After commit d57b2c9 we extracted the code into docs/_dev/check_removed_urls.py, and this introduced the external file dependency that is causing this breakage. You're right, we should checkout sphinx-stack in the workflow, because it allows us to keep the python code in a clean standalone .py file. Here is a PR that should resolve the issue: #624

…

On Tue, 18 Aug 2026 at 02:39, swetha1654 ***@***.***> wrote: *swetha1654* left a comment (canonical/sphinx-stack#612) <#612 (comment)> @jahn-junior <https://github.com/jahn-junior> @rajannpatel <https://github.com/rajannpatel> this PR is causing downstream repos that use the workflow to break <https://github.com/canonical/traefik-k8s-operator/actions/runs/32106678612/job/95617462095?pr=760>. Is it expected now for all downstream repos to have the check_removed_urls python script? Or is this a bug in the workflow where it needs to checkout the same ref of canonical/sphinx-stack that contains the check_removed_urls script? — Reply to this email directly, view it on GitHub <#612?email_source=notifications&email_token=AAC66EKGZDKEVR7XQRZLNLL5KP2Y5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZSGQ2TKMJRGUZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5324551153>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC66EIRCLFMNTA4C4A7IFT5KP2Y5AVCNFSNUABFKJSXA33TNF2G64TZHM2TONJTGMYDQNBVHNEXG43VMU5TINRZGMZDOMBUGE32C5QC> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAC66EN5EKRXMFLA5FC34DT5KP2Y5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZSGQ2TKMJRGUZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/AAC66EJDA3JOGD7OV7AX2SD5KP2Y5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZSGQ2TKMJRGUZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>