[Intermediate]: Add Scheduled Cron Job for Markdown Link Validation

[aceppaluni]

🧩 Intermediate Contributors

This issue is intended for contributors who already have some familiarity with the
Hiero Python SDK codebase and contribution workflow.

You should feel comfortable:

• navigating existing source code and examples
• understanding SDK concepts without step-by-step guidance
• following the standard PR workflow without additional onboarding

If this is your very first contribution to the project, we recommend starting with a few
Good First Issues before working on this one.

🐞 Problem Description

Currently, our workflow checks for broken Markdown links only when pull requests are opened or updated. It could be useful to have a scheduled job that periodically scans the entire codebase for broken links to catch any issues that may have been missed or introduced outside of PRs.

💡 Expected Solution

• Create a GitHub Actions workflow that runs on a schedule (e.g., monthly) to check all Markdown files in the repository.

• Use the existing maintained action tcort/github-action-markdown-link-check for consistency.

• Report any broken links either via the workflow logs or by creating GitHub Issues for any found broken links.

🧠 Implementation Notes

• Create a new GitHub Actions workflow, e.g., .github/workflows/cron-check-broken-links.yml.

• Configure the workflow to run on a cron schedule, e.g., on: schedule: - cron: '0 0 1 * *' for monthly runs.

• Use the existing tcort/github-action-markdown-link-check action to scan all Markdown files in the repository.

• Configure action options similarly to the PR check: use-quiet-mode: 'yes', base-branch: 'main', etc.

• Ensure the workflow reports broken links in a clear way, either via job output or by automatically opening issues/comments.

• Follow the pattern of the current PR check workflow (.github/workflows/pr-check-broken-links.yml) for consistency.

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem described above
• Follow existing project conventions and patterns
• Include tests or example updates where appropriate
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context or Resources

• SDK Developer Docs
• SDK Developer Training

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Fix Broken Links in CONTRIBUTING.md #439
• [Intermediate]: Create workflow that sends a reminder to link an isssue to a PR #1144
• [Good First Issue]: Rename workflows so script and workflow names match #1198
• docs: Standardize absolute GitHub links to relative paths #560
• [Good First Issue]: Rename .github/workflows/pr-missing-linked-issue.yml to .github/workflows/bot-pr-missing-linked-issue.yml #1175

🔗 Related PRs

#1096 - feat: added github workflow that checks test file names (#1054) [merged]
#1123 - feat: Add workflow to notify team about Good first issues [merged]
#1162 - chore: move helpful references to additional context [merged]
#1173 - feat(ci): add workflow to remind pull requests to link issues [merged]
#1187 - feat: implement Linked Issue Enforcer to close PRs without linked issues. [merged]

👤 Suggested Assignees

• exploreriii
• Pranay22077
• HusseinYasser
• kplnosmn94-droid
• andrerovee

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Create a scheduled GitHub Actions workflow that runs monthly to check all Markdown files in the repository for broken links, automatically creating a GitHub Issue when broken links are detected to ensure proactive maintenance of documentation.

Observations

The repository contains 20 GitHub Actions workflows following consistent patterns: security hardening with step-security/harden-runner, pinned checkout actions, granular permissions, and bot-based automation. Five workflows use cron scheduling with workflow_dispatch for manual testing and dry-run capabilities. Bot workflows (12 total) handle issue/PR management using comment-posting mechanisms via actions/github-script with idempotency patterns to prevent duplicate notifications. The contribution workflow requires DCO + GPG-signed commits and changelog updates following the Keep a Changelog format under an [Unreleased] section.

Assumptions

Assumption 1: How to report broken links when failures are detected

Options Considered:

• Report failures only in workflow logs with no automated notifications
• Create a single consolidated GitHub Issue (or update existing) with all broken links when failures are detected

Chosen Option: Create a single consolidated GitHub Issue (or update existing) with all broken links when failures are detected

Rationale: The second approach (automatic issue creation) aligns better with the repository's established bot workflow patterns and provides proactive notification. The monthly schedule means issue frequency won't be excessive, and the repository already has robust infrastructure for idempotent issue management. This approach also follows best practices from web research showing that scheduled workflows should create issues with unique labels and check for existing issues to prevent duplicates.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Scheduled Workflow with Link Checking and Issue Creation

Create a new scheduled workflow that follows established repository patterns for cron jobs, performs markdown link validation, and creates consolidated issues when broken links are detected.

Task 1: Create Base Workflow File

Create the new workflow file at .github/workflows/cron-check-broken-links.yml following repository conventions.

• Include standard security hardening as the first step using step-security/harden-runner@ with egress-policy: audit
• Set up triggers with both schedule (monthly cron: '0 0 1 * *') and workflow_dispatch for manual testing
• Add workflow_dispatch input for dry_run (boolean, default: true) following the pattern from other scheduled workflows
• Declare granular permissions at workflow level: contents: read, issues: write
• Use the pinned checkout action actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 matching other workflows
• Name the workflow descriptively (e.g., "Scheduled Markdown Link Check")

Task 2: Implement Markdown Link Check Step

Add the markdown link checking step using the tcort/github-action-markdown-link-check action.

• Configure the action to scan all markdown files in the repository (no check-modified-files-only flag since this is a full scan)
• Set use-quiet-mode: 'yes' for cleaner output
• Set base-branch: 'main' for consistency
• Configure the step to continue on error (continue-on-error: true) so the workflow can proceed to issue creation even when links are broken
• Store the step outcome in an output variable for conditional issue creation

Task 3: Implement Idempotent Issue Creation

Add a conditional step using actions/github-script@ to create or update a GitHub Issue when broken links are detected.

• Use if: failure() && github.event_name == 'schedule' to run only when link check fails and on scheduled runs (not manual dry runs)
• Search for existing open issues with a unique label (e.g., broken-markdown-links, automated) using the GitHub API
• If an existing issue is found, update it with a comment containing the new findings and current timestamp
• If no existing issue is found, create a new issue with:
  • Title: "Scheduled Markdown Link Check Found Broken Links"
  • Body including timestamp, run ID, link to workflow run, and instruction to check logs for details
  • Unique labels for identification and filtering
  • Consider adding assignee or team mention if applicable
• For dry run mode (manual workflow_dispatch with dry_run: true), log the action that would be taken instead of actually creating/updating issues
• Reference the workflow run URL using ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} in the issue body

🤖 Prompt for AI agents

Create a new scheduled workflow `.github/workflows/cron-check-broken-links.yml`
that performs monthly markdown link validation and creates GitHub issues when
broken links are detected.

Set up workflow structure:
- Add triggers: schedule (cron: '0 0 1 * *') and workflow_dispatch with dry_run
boolean input (default: true)
- Set permissions: contents: read, issues: write
- Name the workflow "Scheduled Markdown Link Check"

Implement workflow steps:
- Add security hardening step using step-security/harden-runner@ with
egress-policy: audit
- Add checkout step using pinned action
actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
- Add markdown link check step using tcort/github-action-markdown-link-check
with use-quiet-mode: 'yes', base-branch: 'main', continue-on-error: true, and
store outcome for conditional logic
- Add conditional issue creation step using actions/github-script@ that runs on
failure() && github.event_name == 'schedule'

Implement idempotent issue management:
- Search for existing open issues with labels 'broken-markdown-links' and
'automated'
- If existing issue found, update with comment containing timestamp and findings
- If no existing issue, create new issue with title "Scheduled Markdown Link
Check Found Broken Links", body with timestamp, run ID, workflow run URL, and
unique labels
- For dry run mode, log actions instead of creating/updating issues

Phase 2: Update Documentation

Update repository documentation to reflect the new workflow capability.

Task 1: Add Changelog Entry

Add an entry to CHANGELOG.md under the [Unreleased] section following Keep a Changelog format.

• Add entry under the ### Added category
• Use format: "Added .github/workflows/cron-check-broken-links.yml workflow to perform scheduled monthly markdown link validation across the entire repository with automatic issue creation for broken links"
• Include reference to this issue/PR number when available

Task 2: Commit with Required Signatures

Ensure all commits follow the repository's contribution requirements.

• Use git commit -S -s to include both GPG signature and DCO sign-off
• Follow conventional commit format in commit messages (e.g., feat: add scheduled markdown link check workflow)

🤖 Prompt for AI agents

Update repository documentation to reflect the new workflow.

Add changelog entry:
- Open CHANGELOG.md and locate [Unreleased] section
- Under ### Added category, add entry: "Added
`.github/workflows/cron-check-broken-links.yml` workflow to perform scheduled
monthly markdown link validation across the entire repository with automatic
issue creation for broken links"
- Include issue/PR reference if available

Commit with proper signatures:
- Use git commit -S -s for GPG signature and DCO sign-off
- Use conventional commit format (e.g., "feat: add scheduled markdown link check
workflow")

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a new scheduled workflow `.github/workflows/cron-check-broken-links.yml`
that performs monthly markdown link validation and creates GitHub issues when
broken links are detected.

Set up workflow structure:
- Add triggers: schedule (cron: '0 0 1 * *') and workflow_dispatch with dry_run
boolean input (default: true)
- Set permissions: contents: read, issues: write
- Name the workflow "Scheduled Markdown Link Check"

Implement workflow steps:
- Add security hardening step using step-security/harden-runner@ with
egress-policy: audit
- Add checkout step using pinned action
actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8
- Add markdown link check step using tcort/github-action-markdown-link-check
with use-quiet-mode: 'yes', base-branch: 'main', continue-on-error: true, and
store outcome for conditional logic
- Add conditional issue creation step using actions/github-script@ that runs on
failure() && github.event_name == 'schedule'

Implement idempotent issue management:
- Search for existing open issues with labels 'broken-markdown-links' and
'automated'
- If existing issue found, update with comment containing timestamp and findings
- If no existing issue, create new issue with title "Scheduled Markdown Link
Check Found Broken Links", body with timestamp, run ID, workflow run URL, and
unique labels
- For dry run mode, log actions instead of creating/updating issues
===============================================================================

Task: 2

Update repository documentation to reflect the new workflow.

Add changelog entry:
- Open CHANGELOG.md and locate [Unreleased] section
- Under ### Added category, add entry: "Added
`.github/workflows/cron-check-broken-links.yml` workflow to perform scheduled
monthly markdown link validation across the entire repository with automatic
issue creation for broken links"
- Include issue/PR reference if available

Commit with proper signatures:
- Use git commit -S -s for GPG signature and DCO sign-off
- Use conventional commit format (e.g., "feat: add scheduled markdown link check
workflow")

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[drtoxic69]

Hi, @aceppaluni
I found this issue interesting and would like to work on it.

[exploreriii]

I have questions how it would work
While I like the idea of having a monthly check up of URLs, I don't know how to 'publish the results'
We would have to create some kind of automatic pull request, but then this suggests we would need to know what the url would become.
Else how do we create an automatic issue creation?
@drtoxic69 have you thought more about how it would work? Or would it just have to be a runnable script ?

[drtoxic69]

Hi @exploreriii

You are right, an automatic PR wouldn't work because the bot can't know the correct URL to fix it.

My proposal is to use an Automated GitHub Issue just for reporting:

1. The workflow runs the link checker monthly.

2. If it finds broken links, it checks if an issue labeled broken-markdown-links is already open.

   • If No: It creates a new issue linking to the failed logs.

   • If Yes: It adds a comment to the existing issue (to avoid spamming duplicates).

This ensures the team is notified of broken links without needing complex logic to guess the fixes.

[exploreriii]

Excellent! Assigned @drtoxic69
Thanks for looking into it - I suppose you'll have to look carefully at the permissions for that
Please do ask if you have any questions and thank you