Add docs broken link checker CI workflow and fix broken links by devin-ai-integration[bot] · Pull Request #21250 · PrefectHQ/prefect

devin-ai-integration · 2026-03-24T01:42:34Z

Adds a dedicated GitHub Actions workflow that runs the existing just links command from docs/justfile to catch broken internal links in docs via Mintlify's broken-links CLI.

The workflow:

Triggers on PRs and pushes to main when docs/** files are modified
Delegates to just links (uses extractions/setup-just@v3, consistent with integration-package-release.yaml)
Supports workflow_dispatch for manual runs
Uses the same concurrency and path-filtering patterns as existing CI workflows (e.g. markdown-tests.yaml)

The command was already available via docs/justfile (just links) but was not wired into CI.

Also fixes all broken links and MDX parsing errors caught by the checker:

MDX parsing fixes — Bare curly braces in docstrings (e.g. {'pod_name': 'pod_log_str'}) were interpreted as JSX expressions by the Mintlify MDX parser. Fixed by wrapping them in backticks in the source docstrings and regenerating the affected API ref docs via mdxify.

Broken link fixes across 7 files:

infrastructure-as-code.mdx: add missing https:// to Pulumi URL
deployments.mdx: update ECS guide path (ecs_guide#ecs-worker-guide → ecs-worker)
task-runners.mdx: fix States API ref path (prefect-server#prefect.server.schemas.states → prefect-server-schemas-states)
resume-flow-run-on-pr-merge.mdx: fix webhooks path (/v3/automate/events/webhooks → /v3/concepts/webhooks)
version-3-2.mdx, version-3-3.mdx, version-3-4.mdx: fix malformed markdown PR links (nested [text]([#num](url)) → [text](url))

Closes #13978

Things for reviewers to consider

mint@latest — consistent with the existing docs/justfile, but pins to no specific version. A Mintlify breaking change could cause unexpected workflow failures.
ECS link change — ecs_guide#ecs-worker-guide was replaced with ecs-worker based on the current directory structure (docs/integrations/prefect-aws/ecs-worker/index.mdx). Worth verifying this resolves correctly in the deployed docs.
Regenerated docs include a line-number shift in prefect_kubernetes-observer.mdx — this is expected from mdxify picking up upstream source changes; no content was altered.

Checklist

This pull request references any related issue by including "closes <link to issue>"
If this pull request adds new functionality, it includes unit tests that cover the changes
If this pull request removes docs files, it includes redirect settings in mint.json.
If this pull request adds functions or classes, it includes helpful docstrings.

Link to Devin session: https://app.devin.ai/sessions/3b47cf2e5966481087098e76606be880
Requested by: @desertaxle

Adds a local pre-commit hook that runs Mintlify's broken-links checker when files in docs/ are modified. Closes #13978 Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration · 2026-03-24T01:42:37Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment and CI monitoring

Replaces the pre-commit hook with a dedicated GitHub Actions workflow that runs Mintlify's broken-links checker on PRs and pushes to main when docs/ files are modified. Closes #13978 Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

Wrap bare curly braces in backticks in docstrings so the generated MDX does not trip the Mintlify parser (acorn treats them as JSX expressions). Affected source files: - prefect_kubernetes/flows.py: {'pod_name': ...} -> `{'pod_name': ...}` - prefect/server/models/workers.py: {work_queue_id: count} -> `{...}` Regenerated docs: - docs/integrations/prefect-kubernetes/api-ref/prefect_kubernetes-flows.mdx - docs/integrations/prefect-kubernetes/api-ref/prefect_kubernetes-observer.mdx - docs/v3/api-ref/python/prefect-server-models-workers.mdx Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

codspeed-hq · 2026-03-24T02:33:17Z

Merging this PR will not alter performance

✅ 2 untouched benchmarks

_{Comparing devin/1774316441-docs-broken-link-checker (990fb67) with main (38894ab)}

- infrastructure-as-code.mdx: add missing https:// to Pulumi URL - deployments.mdx: update ECS guide path to /integrations/prefect-aws/ecs-worker - task-runners.mdx: fix States API ref path to prefect-server-schemas-states - resume-flow-run-on-pr-merge.mdx: fix webhooks path to /v3/concepts/webhooks - version-3-2.mdx: fix malformed markdown PR links (#17240, #17123) - version-3-3.mdx: fix malformed markdown PR links (#17747, #17671) - version-3-4.mdx: fix malformed markdown PR link (#18004) Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

desertaxle · 2026-03-24T14:11:34Z

.github/workflows/docs-broken-links.yaml

+
+      - name: Check for broken links
+        working-directory: docs
+        run: npx mint@latest broken-links


Can we use the broken-links command in docs/justfile instead?

Done — updated to use just links via extractions/setup-just@v3 (same action used in integration-package-release.yaml).

Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 71603ea01d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-03-24T14:46:17Z

docs/v3/examples/resume-flow-run-on-pr-merge.mdx


 <Note>
-This example uses [webhooks](/v3/automate/events/webhooks), which are only available in Prefect Cloud.
+This example uses [webhooks](/v3/concepts/webhooks), which are only available in Prefect Cloud.


Fix webhook link in the example source file

This edit updates an auto-generated page (docs/v3/examples/...) but not its source template in examples/resume_flow_run_on_pr_merge.py (which still contains /v3/automate/events/webhooks), so the next docs regeneration will overwrite this line and reintroduce the broken link. To make the fix durable, the source example comment should be updated and the page regenerated.

Useful? React with 👍 / 👎.

Good catch — fixed in 990fb67. Updated the source file examples/resume_flow_run_on_pr_merge.py so regeneration won't revert the link fix.

Update the source template so regeneration does not revert the fix. Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.

Add docs broken link checker to pre-commit hooks

76dc3f6

Adds a local pre-commit hook that runs Mintlify's broken-links checker when files in docs/ are modified. Closes #13978 Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration bot assigned desertaxle Mar 24, 2026

github-actions bot added the docs label Mar 24, 2026

devin-ai-integration bot changed the title ~~Add docs broken link checker to pre-commit hooks~~ Add docs broken link checker CI workflow Mar 24, 2026

desertaxle requested changes Mar 24, 2026

View reviewed changes

Use just links from docs/justfile in CI workflow

71603ea

Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration bot changed the title ~~Add docs broken link checker CI workflow~~ Add docs broken link checker CI workflow and fix broken links Mar 24, 2026

desertaxle marked this pull request as ready for review March 24, 2026 14:42

desertaxle requested review from chrisguidry, cicdw and zzstoatzz as code owners March 24, 2026 14:42

chatgpt-codex-connector bot reviewed Mar 24, 2026

View reviewed changes

Fix webhook link in example source file

990fb67

Update the source template so regeneration does not revert the fix. Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

desertaxle approved these changes Mar 24, 2026

View reviewed changes

desertaxle merged commit ea79b8f into main Mar 24, 2026
95 of 96 checks passed

desertaxle deleted the devin/1774316441-docs-broken-link-checker branch March 24, 2026 15:07

devin-ai-integration bot commented Mar 24, 2026

View reviewed changes

devin-ai-integration bot mentioned this pull request Apr 6, 2026

docs: Add release notes for prefect-kubernetes==0.7.7 #21434

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs broken link checker CI workflow and fix broken links#21250

Add docs broken link checker CI workflow and fix broken links#21250
desertaxle merged 6 commits intomainfrom
devin/1774316441-docs-broken-link-checker

devin-ai-integration bot commented Mar 24, 2026 •

edited

Loading

Uh oh!

devin-ai-integration bot commented Mar 24, 2026

Uh oh!

codspeed-hq bot commented Mar 24, 2026 •

edited

Loading

Uh oh!

desertaxle Mar 24, 2026

Uh oh!

devin-ai-integration bot Mar 24, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

chatgpt-codex-connector bot Mar 24, 2026

Uh oh!

devin-ai-integration bot Mar 24, 2026

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

devin-ai-integration bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Things for reviewers to consider

Checklist

Uh oh!

devin-ai-integration bot commented Mar 24, 2026

🤖 Devin AI Engineer

Uh oh!

codspeed-hq bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

desertaxle Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

devin-ai-integration bot commented Mar 24, 2026 •

edited

Loading

codspeed-hq bot commented Mar 24, 2026 •

edited

Loading