https://github.com/liskin/gh-linkchecker

https://github.com/liskin/gh-linkchecker

ci continuous-integration github github-actions github-pages link-check link-checker link-checking

Last synced: about 1 month ago
JSON representation

• Host: GitHub
• URL: https://github.com/liskin/gh-linkchecker
• Owner: liskin
• License: mit
• Created: 2024-05-18T18:05:15.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2024-05-19T22:52:19.000Z (8 months ago)
• Last Synced: 2024-10-16T00:44:30.888Z (3 months ago)
• Topics: ci, continuous-integration, github, github-actions, github-pages, link-check, link-checker, link-checking
• Language: Shell
• Homepage:
• Size: 13.7 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# GitHub Action: linkchecker

GitHub Action that checks links using

[LinkChecker](https://linkchecker.github.io/linkchecker/).

Features:

* [LinkChecker features](https://linkchecker.github.io/linkchecker/#features)

* retry failures

* output to GitHub as error/warning/notice annotations

* custom [jq](https://jqlang.github.io/jq/) filters that can be used to

  implement complex ignore rules that can't be expressed in linkcheckerrc,

  such as turning warnings or ignoring only temporary redirects but not

  permanent redirects

## Usage

### Basic Example - check external links and anchors of your GitHub Pages

```yaml

name: Check for broken links

on:

  workflow_dispatch:

  schedule:

    # Run every weekend

    - cron: '0 2 * * 6'

jobs:

  linkchecker:

    runs-on: ubuntu-latest

    steps:

      - uses: liskin/[email protected]

        with:

          retries: 3

          linkcheckerrc: |

            [filtering]

            checkextern=1

            [AnchorCheck]

```

### Advanced Example - tweak severity of redirects

```yaml

      - uses: liskin/[email protected]

        with:

          # …

          linkcheckerrc: |

            [filtering]

            checkextern=1

          custom-jq-filter-post: |

            def moved_permanently_to_error:

                if is_warning and (.warning | contains("status: 301 ")) then

                    to_error

                end;

            def moved_temporarily_to_info:

                if is_warning and (.warning | contains("status: 302 ")) then

                    to_info

                end;

            map(

                moved_permanently_to_error |

                moved_temporarily_to_info

            )

```

Other examples of advanced custom jq filter usage:

* 

### Parameters

* `urls`

    * Space-separated list of URLs to crawl

    * (Default: GitHub Pages URL of the invoking repository)

* `linkcheckerrc`

    * Configuration file for LinkChecker

    * (Default: empty)

* `custom-jq-filter`

    * Custom jq filter/program that can be used to implement complex ignore

      rules that can't be expressed in linkcheckerrc.

      This filter is run after every linkchecker attempt, so using it to

      upgrade warnings to errors will cause retries.

    * Helper functions from [linkchecker.jq](linkchecker.jq) are available.

    * (Default: `.`)

* `custom-jq-filter-post`

    * Custom jq filter/program that can be used to implement complex ignore

      rules that can't be expressed in linkcheckerrc, such as turning warnings

      into errors or ignoring only temporary redirects but not permanent

      redirects.

      This filter is run after a successful (no errors) linkchecker attempt.

    * Helper functions from [linkchecker.jq](linkchecker.jq) are available.

    * (Default: `.`)

* `retries`

    * Maximum number of retries (if there are any errors)

    * (Default: 1)