How to set up GitHub Actions to automatically check links in README.md?

[minx-nie]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Misc

Discussion Details

Hi everyone,

I'm maintaining a repository with a curated list of APIs in README.md. The list is growing and I want to automatically check if any links become broken.

What I need:

• A GitHub Actions workflow that runs periodically (e.g., weekly)
• Checks all URLs in README.md
• Creates an issue or notifies me if any links are dead

I've seen some link checker actions but I'm not sure which one to use or how to configure it properly.

Any help would be appreciated! 🙏

[shivaganesht]

I can help you with this! Here's a complete solution using the lychee-action which is a popular GitHub Action for link checking:

Solution

Create a new file .github/workflows/link-checker.yml:

name: Check Links
on:
schedule:
- cron: '0 0 * * 0'
workflow_dispatch:

jobs:
lychee:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: lycheeverse/lychee-action@v1
with:
args: --markdown README.md
fail: true

How it works:

1. Runs weekly on Sunday at midnight
2. Checks all links in README.md
3. Fails the workflow if broken links are found
4. You can create an issue using GitHub Actions script if needed

This is the recommended approach for link checking in GitHub Actions. Hope this helps!

[ThanhNguyxn]

Hi @minx-nie,

Great question! Here's a complete solution for automated link checking:

Option 1: Using lychee (Recommended)

Create .github/workflows/link-checker.yml:

name: Link Checkeron: schedule: - cron: '0 0 * * 0'# Every Sunday at midnightworkflow_dispatch: # Allow manual triggerjobs: check-links: runs-on: ubuntu-lateststeps: - uses: actions/checkout@v4 - name: Check Linksuses: lycheeverse/lychee-action@v1with: args: --verbose --no-progress README.mdfail: true - name: Create Issue on Failureif: failure()uses: actions/github-script@v7with: script: | github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: '🔗 Broken links detected', body: 'The link checker found broken links. Check the workflow run for details.' })

Option 2: Custom Python Script

For more control, you can write a custom script that:

• Extracts URLs using regex
• Checks each URL with retries
• Handles rate limiting (403/429 errors)
• Generates detailed reports

Key Tips:

• Use workflow_dispatch to test manually first
• Add timeout for slow URLs
• Exclude false positives with .lycheeignore

Hope this helps! 🚀