Published on

Creating a scheduled Broken Links Checker using Github Actions


Follow this tutorial if you want to prevent dead links creeping into your website.

After completing all steps you will have created a simple Github action that:

  • Does a monthly check against your live website
  • Creates a Github Issue if broken links are detected
  • Optionally assigns a label and/or assignee to the issue

Example Github Issue

Example Github Issue if Broken Links are detected

1. Create the Action

  1. Ceate folder .github/workflows
  2. In that folder, create file check-broken-links.yml
  3. Insert below code into the newly created file and make sure to update WEBSITE_URL so it matches your live website:
name: Broken Links Checker
    - cron:  '0 1 1 * *'
  ISSUE_TEMPLATE: ".github/workflows/"

    runs-on: ubuntu-latest

    - name: Run Broken Links Checker
      run: npx broken-link-checker $WEBSITE_URL --ordered --recursive

    - uses: actions/checkout@v2
      if: failure()

    - uses: JasonEtco/create-an-issue@main
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        filename: ${{ env.ISSUE_TEMPLATE }}
      if: failure()


2. Create the Issue Template

All that is left now is creating a markodwn template that will be used to create the Github Issue.

  1. Inside folder .github/workflows, create file
  2. Insert below code into the newly created file and make sure to:
    • Replace the website URL
    • Replace the github repository
title: Website Contains Broken Links
labels: housekeeping
assignees: ''

## Website Contains Broken Links

Broken Link Checker found :coffin: links on

[View Results]({{sha}}/checks)

_Use search filter `─BROKEN─` to highlight failures_


  • The View Results link uses the commit hash to point directly to the corresponding Github Actions log


All done, you will now be notified if any dead links are detected on your live website.

To run the analysis from your local machine use:

npx broken-link-checker --ordered --recursive

To determine which links need fixing:

  1. Open the Github Actions log by clicking on the View results link (in the Github Issue)
  2. Expand the log for action "Run Broken Links Checker"
  3. Optionally use search filter ─BROKEN─ to highlight dead links
  4. Analyze and solve as needed
Example Github Action Log