INTEGRATION · GITHUB ACTION

Checkredirects.io GitHub Action

Check URLs for redirects, broken links, and errors as part of your CI/CD pipeline. Fail builds on problems, post results as PR comments.

GitHub API docs

Quick start

Add this to .github/workflows/check-redirects.yml:

name: Check Redirects
on: [push, pull_request]

permissions:
  contents: read
  pull-requests: write   # required for the PR comment

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: neondeerdatalabs/checkredirects-action@v1
        with:
          api-key: $${{ secrets.CHECKREDIRECTS_API_KEY }}
          urls: |
            https://example.com
            https://example.com/old-page

Inputs

Input	Default	Description
`api-key`	—	Required. Your API key (starts with `httpnd_`).
`urls`	—	URLs to check, one per line. Provide exactly one of `urls`, `urls-file`, or `sitemap`.
`urls-file`	—	Path to a file with one URL per line (relative to the workspace).
`sitemap`	—	Sitemap URL. Parsed server-side, including sitemap indexes.
`fail-on-error`	`true`	Fail if any URL has a 4xx/5xx final status or a connection error.
`fail-on-redirect`	`false`	Fail if any URL redirects (one or more hops).
`fail-on-chain`	`false`	Fail if any URL has two or more hops.
`user-agent`	—	Preset (e.g. `googlebot`) or a custom string.
`max-redirects`	`10`	Maximum redirects to follow per URL.
`https-only`	`false`	When true, don't fall back to HTTP if HTTPS fails.
`share-results`	`false`	Create a public share link and include it in the PR comment. Off by default; results stay private.
`comment-on-pr`	`true`	Upsert a single PR comment with the summary. No-op on push events.
`dedupe`	`true`	Remove duplicate URLs before submission. Duplicates removed are reported in the summary.
`timeout-seconds`	`300`	Maximum wall-clock seconds to wait for the batch.
`base-url`	`https://api.checkredirects.io`	Override for staging or self-hosted.

Outputs

Output	Description
`total`	URLs submitted after dedupe.
`completed`	URLs that returned a final status without a connection error.
`errors`	URLs with a 4xx/5xx final status or a connection error.
`redirects`	URLs that redirected (one or more hops).
`chains`	URLs with a redirect chain (two or more hops).
`pass`	`true` if no fail-on threshold was hit.
`batch-id`	Batch job ID; use it to fetch full results from the API later.
`share-url`	Public share URL (only set when `share-results: true`).
`results-json`	Path under `$RUNNER_TEMP` to a JSON file with the full merged results.

PR comments

On pull request events the action upserts a single comment (one per PR, edited on later runs). It needs pull-requests: write permission. PRs from forks have a read-only token, so the action will write the summary to the step output and warn, but won't fail just because it couldn't comment.

Use cases

Post-migration validation: Check all old URLs still redirect correctly after a deploy
Link rot prevention: Verify external links in your docs or README on every push
Redirect chain enforcement: Fail the build if any URL has more than one hop
Sitemap health: Import your sitemap and check every URL on a schedule

Add redirect checks to your CI pipeline

Free plan includes 250 checks per month. No credit card required.