{"id":13554595,"url":"https://github.com/lycheeverse/lychee-action","last_synced_at":"2025-05-14T05:10:45.737Z","repository":{"id":38415762,"uuid":"320929718","full_name":"lycheeverse/lychee-action","owner":"lycheeverse","description":"Github action to check for broken links in Markdown, HTML, and text files using lychee, a fast link checker written in Rust.","archived":false,"fork":false,"pushed_at":"2025-05-09T09:32:54.000Z","size":226,"stargazers_count":364,"open_issues_count":5,"forks_count":53,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-10T22:32:48.473Z","etag":null,"topics":["action","continuous-integration","github-actions","link-checker"],"latest_commit_sha":null,"homepage":"https://lychee.cli.rs","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lycheeverse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"lychee-collective","github":"mre"}},"created_at":"2020-12-12T21:41:36.000Z","updated_at":"2025-05-09T02:34:38.000Z","dependencies_parsed_at":"2023-01-11T17:21:31.502Z","dependency_job_id":"e2c7b869-f8f5-48a8-a502-819a5cb2d079","html_url":"https://github.com/lycheeverse/lychee-action","commit_stats":{"total_commits":201,"total_committers":36,"mean_commits":5.583333333333333,"dds":0.3880597014925373,"last_synced_commit":"ae4699150ab670dcfb64cc74e8680e776d9caae2"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lycheeverse%2Flychee-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lycheeverse%2Flychee-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lycheeverse%2Flychee-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lycheeverse%2Flychee-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lycheeverse","download_url":"https://codeload.github.com/lycheeverse/lychee-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253518943,"owners_count":21921074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["action","continuous-integration","github-actions","link-checker"],"created_at":"2024-08-01T12:02:50.973Z","updated_at":"2025-05-14T05:10:45.686Z","avatar_url":"https://github.com/lycheeverse.png","language":"Shell","funding_links":["https://opencollective.com/lychee-collective","https://github.com/sponsors/mre"],"categories":["Shell","continuous-integration"],"sub_categories":[],"readme":"# lychee link checking action\n\n[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-lychee-blue.svg?colorA=24292e\u0026colorB=0366d6\u0026style=flat\u0026longCache=true\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/lychee-broken-link-checker)\n[![Check Links](https://github.com/lycheeverse/lychee-action/actions/workflows/links.yml/badge.svg)](https://github.com/lycheeverse/lychee-action/actions/workflows/links.yml)\n\nQuickly check links in Markdown, HTML, and text files using [lychee].\n\nWhen used in conjunction with [Create Issue From File], issues will be\nopened when the action finds link problems (make sure to specify the `issues: write` permission in the [workflow](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#permissions) or the [job](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions)).\n\n## Usage\n\nHere is a full example of a GitHub workflow file:\n\nIt will check all repository links once per day and create an issue in case of\nerrors. Save this under `.github/workflows/links.yml`:\n\n```yaml\nname: Links\n\non:\n  repository_dispatch:\n  workflow_dispatch:\n  schedule:\n    - cron: \"00 18 * * *\"\n\njobs:\n  linkChecker:\n    runs-on: ubuntu-latest\n    permissions:\n      issues: write # required for peter-evans/create-issue-from-file\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Link Checker\n        id: lychee\n        uses: lycheeverse/lychee-action@v2\n        with:\n          fail: false\n\n      - name: Create Issue From File\n        if: steps.lychee.outputs.exit_code != 0\n        uses: peter-evans/create-issue-from-file@v5\n        with:\n          title: Link Checker Report\n          content-filepath: ./lychee/out.md\n          labels: report, automated issue\n```\n\n## Passing arguments\n\nThis action uses [lychee] for link checking.\nlychee arguments can be passed to the action via the `args` parameter.\n\nOn top of that, the action also supports some additional arguments.\n\n| Argument         | Examples                | Description                                                                             |\n| ---------------- | ----------------------- | --------------------------------------------------------------------------------------- |\n| args             | `--cache`, `--insecure` | See [lychee's documentation][lychee-args] for all arguments and values                  |\n| debug            | `false`                 | Enable debug output in action (set -x). Helpful for troubleshooting                     |\n| fail             | `false`                 | Fail workflow run on error (i.e. when [lychee exit code][lychee-exit] is not 0)         |\n| failIfEmpty      | `false`                 | Fail entire pipeline if no links were found                                             |\n| format           | `markdown`, `json`      | Summary output format                                                                   |\n| jobSummary       | `false`                 | Write GitHub job summary (on Markdown output only)                                      |\n| lycheeVersion    | `v0.15.0`, `nightly`    | Overwrite the lychee version to be used                                                 |\n| output           | `lychee/results.md`     | Summary output file path                                                                |\n| token            | `\"\"`                    | Custom GitHub token to use for API calls                                                |\n| workingDirectory | `.`, `path/to/subdir/`  | Custom working directory to run lychee in. This affects where `output.md` gets created. |\n\nSee [action.yml](./action.yml) for a full list of supported arguments and their default values.\n\n### Passing arguments\n\nHere is how to pass the arguments.\n\n```yml\n- name: Link Checker\n  uses: lycheeverse/lychee-action@v2\n  with:\n    # Check all markdown, html and reStructuredText files in repo (default)\n    args: --base . --verbose --no-progress './**/*.md' './**/*.html' './**/*.rst'\n    # Use json as output format (instead of markdown)\n    format: json\n    # Use different output file path\n    output: /tmp/foo.txt\n    # Use a custom GitHub token, which\n    token: ${{ secrets.CUSTOM_TOKEN }}\n    # Don't fail action on broken links\n    fail: false\n    # Run lychee in a different directory.\n    # Note: This changes the lychee output directory as well.\n    workingDirectory: website/subdir\n```\n\n(If you need a token that requires permissions that aren't available in the\ndefault `GITHUB_TOKEN`, you can create a [personal access\ntoken](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)\nand pass it to the action via the `token` parameter.)\n\n## Utilising the cache feature\n\nIn order to mitigate issues regarding rate limiting or to reduce stress on external resources, one can setup lychee's cache similar to this:\n\n```yml\n- name: Restore lychee cache\n  uses: actions/cache@v4\n  with:\n    path: .lycheecache\n    key: cache-lychee-${{ github.sha }}\n    restore-keys: cache-lychee-\n\n- name: Run lychee\n  uses: lycheeverse/lychee-action@v2\n  with:\n    args: \"--base . --cache --max-cache-age 1d .\"\n```\n\nIt will compare and save the cache based on the given key.\nSo in this setup, as long as a user triggers the CI run from the same commit, it will be the same key. The first run will save the cache, subsequent runs will not update it (because it's the same commit hash).\nFor restoring the cache, the most recent available one is used (commit hash doesn't matter).\n\nIf you need more control over when caches are restored and saved, you can split the cache step and e.g. ensure to always save the cache (also when the link check step fails):\n\n```yml\n- name: Restore lychee cache\n  id: restore-cache\n  uses: actions/cache/restore@v4\n  with:\n    path: .lycheecache\n    key: cache-lychee-${{ github.sha }}\n    restore-keys: cache-lychee-\n\n- name: Run lychee\n  uses: lycheeverse/lychee-action@v2\n  with:\n    args: \"--base . --cache --max-cache-age 1d .\"\n\n- name: Save lychee cache\n  uses: actions/cache/save@v4\n  if: always()\n  with:\n    path: .lycheecache\n    key: ${{ steps.restore-cache.outputs.cache-primary-key }}\n```\n\n## Excluding links from getting checked\n\nAdd a `.lycheeignore` file to the root of your repository to exclude links from\ngetting checked. It supports regular expressions. One expression per line.\n\nYou can also put your `.lycheeignore` into a subdirectory if you set that as the `workingDirectory`.\n\n## Fancy badge\n\nPro tip: You can add a little badge to your repo to show the status of your\nlinks. Just replace `org` with your organisation name and `repo` with the\nrepository name and put it into your `README.md`:\n\n```\n[![Check Links](https://github.com/org/repo/actions/workflows/links.yml/badge.svg)](https://github.com/org/repo/actions/workflows/links.yml)\n```\n\nIt will look like this:\n\n[![Check Links](https://github.com/lycheeverse/lychee-action/actions/workflows/links.yml/badge.svg)](https://github.com/lycheeverse/lychee-action/actions/workflows/links.yml)\n\n## Troubleshooting and common problems\n\nSee [lychee's Troubleshooting Guide][troubleshooting] for solutions to common\nlink-checking problems.\n\n## Performance\n\nA full CI run to scan 576 links takes approximately 1 minute for the\n[analysis-tools-dev/static-analysis](https://github.com/analysis-tools-dev/static-analysis)\nrepository.\n\n## Security and Updates\n\nIt is recommended to pin lychee-action to a fixed version [for security\nreasons][security]. You can use dependabot to automatically keep your GitHub\nactions up-to-date. This is a great way to pin lychee-action, while still\nreceiving updates in the future. It's a relatively easy thing to do.\n\nCreate a file named `.github/dependabot.yml` with the following contents:\n\n```yml\nversion: 2\nupdates:\n  - package-ecosystem: \"github-actions\"\n    directory: \".github/workflows\"\n    schedule:\n      interval: \"daily\"\n```\n\nWhen you add or update the `dependabot.yml` file, this triggers an immediate check for version updates.\nPlease see [the documentation][dependabot] for all configuration options.\n\n### Security tip\n\nFor additional security when relying on automation to update actions you can pin\nthe action to a SHA-256 rather than the semver version so as to avoid tag\nspoofing Dependabot will still be able to automatically update this.\n\nFor example:\n\n```yml\n- name: Link Checker\n  uses: lycheeverse/lychee-action@7da8ec1fc4e01b5a12062ac6c589c10a4ce70d67 # for v2.0.0\n```\n\n## Credits\n\nThis action is based on the deprecated [peter-evans/link-checker] and uses\n[lychee] (written in Rust) instead of liche (written in Go) for link checking.\n\n## License\n\nlychee is licensed under either of\n\n- [Apache License, Version 2.0] ([LICENSE-APACHE](./LICENSE-APACHE))\n- [MIT License] ([LICENSE-MIT](./LICENSE-MIT))\n\nat your option.\n\n[lychee]: https://github.com/lycheeverse/lychee\n[lychee-args]: https://github.com/lycheeverse/lychee#commandline-parameters\n[lychee-exit]: https://github.com/lycheeverse/lychee#exit-codes\n[troubleshooting]: https://github.com/lycheeverse/lychee/blob/master/docs/TROUBLESHOOTING.md\n[security]: https://francoisbest.com/posts/2020/the-security-of-github-actions\n[dependabot]: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file\n[peter-evans/link-checker]: https://github.com/peter-evans/link-checker\n[create issue from file]: https://github.com/peter-evans/create-issue-from-file\n[apache license, version 2.0]: https://www.apache.org/licenses/LICENSE-2.0\n[mit license]: https://choosealicense.com/licenses/mit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flycheeverse%2Flychee-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flycheeverse%2Flychee-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flycheeverse%2Flychee-action/lists"}