lychee.toml

# Lychee link checker configuration
# https://github.com/lycheeverse/lychee
#
# Run locally: atmos lint link-check
# Or directly: lychee --config lychee.toml '**/*.md'

# Log level: "error", "warn", "info", "debug", "trace"
verbose = "info"

# Don't show progress bar (cleaner CI output)
no_progress = true

# Timeout for each request (seconds)
timeout = 60

# Retry failed requests
max_retries = 3

# Accept these HTTP status codes as valid.
# 500/502/504 are included alongside 403/429 because GitHub's gateway
# intermittently rejects a handful of the ~800 unique links checked here with
# 500 Internal Server Error, 502 Bad Gateway, or 504 Gateway Timeout under
# CI's request volume (verified to return 200 outside CI), spanning arbitrary
# github.com issue/PR/tree/blob/release/user URLs across different repos —
# not any one specific broken link. See the v1.203.0 release-tag exclude below
# for the single-URL precedent of this same GitHub-gateway flakiness; the
# narrower google-gemini/gemini-cli and gruntwork-io/terragrunt excludes are
# for repos that showed 502s repeatedly before this status code was accepted
# broadly.
# 503/520 cover the same class of flakiness on (img.)shields.io badge URLs,
# which intermittently reject requests under CI's request volume.
accept = ["200", "204", "301", "302", "403", "429", "500", "502", "503", "504", "520"]

# Paths to exclude from checking (input files to scan)
exclude_path = [
  "website",
  "node_modules",
  ".git",
  ".conductor",
  # Go template files (badge URLs contain unrendered `{{ }}` placeholders,
  # e.g. pkg/ci/plugins/terraform/templates/test.md) — not real documentation.
  "pkg/ci",
]

# URL patterns to exclude (regex)
exclude = [
  "localhost",
  "127\\.0\\.0\\.1",
  "example\\.com",
  "cpco\\.io",
  "cloudposse\\.com.*utm_",
  # Private GitHub org (not accessible to CI)
  "github\\.com/cloudposse-corp",
  "slack\\.cloudposse\\.com",
  "wttr\\.in",
  # GNU.org (rate limits and connection resets)
  "gnu\\.org",
  # The Linux Documentation Project (intermittent 502 Bad Gateway in CI)
  "tldp\\.org",
  # Linux Foundation specs (slow response times)
  "refspecs\\.linuxfoundation\\.org",
  # OpenBSD man pages (slow response times, intermittent timeouts in CI)
  "man\\.openbsd\\.org",
  # Kubernetes.io (rate limits and connection resets in CI)
  "kubernetes\\.io",
  # runatlantis.io (connection resets on automated requests)
  "runatlantis\\.io",
  # GitHub docs (intermittent 503s in CI)
  "docs\\.github\\.com",
  # npm package-lock documentation intermittently returns 503 from CI runners;
  # the canonical page returns 200 outside that transient upstream failure.
  "docs\\.npmjs\\.com/cli/v10/configuring-npm/package-lock-json/?$",
  # Cloudinary image resizing proxy
  "img\\.cloudposse\\.com",
  # atmos.tools URLs (can't verify website links locally)
  "atmos\\.tools",
  # Root-relative paths converted to file:// URLs (atmos.tools website paths)
  "file://.*/cli/",
  "file://.*/functions/",
  # Files that don't exist yet (planned documentation)
  "website/docs/cli/errors\\.mdx",
  "website/docs/cli/configuration/mask\\.mdx",
  # Documentation template placeholder (intentional)
  "github\\.com/cloudposse/atmos/issues/XXXX",
  # GitHub redirects (expected behavior)
  "github\\.com/cloudposse/atmos/releases/latest",
  "github\\.com/codespaces",
  # Raw file URLs redirect through GitHub's CDN (by design)
  "\\?raw=true",
  # shields.io (both the bare domain and the img. subdomain used for dynamic
  # GitHub badges) is Cloudflare-fronted and intermittently returns non-200
  # (500, 520 "Unknown Error") to automated/CI requests -- confirmed across
  # multiple unrelated badge paths in different files, and reproduced outside
  # CI too (curl returning 200 and 520 on back-to-back requests to the same
  # badge). The badges render fine in a browser. Supersedes narrower
  # path-scoped excludes for the same domain (img.shields.io/github/release/,
  # shields.io/badge/, img.shields.io/github/(actions/workflow/status|last-commit)/).
  "shields\\.io",
  # Atmos Pro redirects to sign-in page for unauthenticated users
  "atmos-pro\\.com",
  # LF AI Foundation blog links (may change or be unavailable)
  "lfaidata\\.foundation",
  # Taskfile.dev (connection resets in CI)
  "taskfile\\.dev",
  # Gemini CLI documentation resets connections from GitHub-hosted runners.
  "geminicli\\.com",
  # Concourse's public site intermittently resets CI connections.
  "concourse-ci\\.org",
  # Aqua's documentation host intermittently returns 503 from CI runners.
  "aquaproj\\.github\\.io",
  # Gomplate docs (connection resets in CI)
  "docs\\.gomplate\\.ca",
  # regex101.com (intermittent timeouts in CI)
  "regex101\\.com",
  # nx.dev (intermittent connection failures in CI)
  "nx\\.dev",
  # Test data placeholder URLs (intentional)
  "github\\.com/test/",
  # Planned documentation paths (not yet published)
  "file://.*/ai/skills",
  "file://.*/ai/skill-marketplace",
  # Example/placeholder URLs in usage documentation
  "github\\.com/user/repo",
  # Claude Code product page (claude.com edge returns 500 to non-browser/CI requests)
  "claude\\.com/product/",
  # Claude Code docs (code.claude.com) now exhibit the same CI-hostile pattern as
  # docs.anthropic.com/platform.openai.com/clau.de below: requests from CI runners
  # 302-redirect to https://dns.google/<same-path> (a DNS-sinkhole-style artifact,
  # not a real site redirect) before 404ing, while the pages resolve normally and
  # are correctly indexed by search engines when fetched from a real browser.
  "code\\.claude\\.com",
  # regex101.com (intermittent 504 Gateway Timeout in CI)
  "regex101\\.com",
  # Anthropic's clau.de URL shortener is Cloudflare-fronted and returns 525
  # (SSL handshake failed) to non-browser/CI requests; it resolves in a real browser.
  "clau\\.de",
  # Anthropic docs intermittently return 503 Service Unavailable from CI runners.
  "docs\\.anthropic\\.com",
  # OpenAI's docs (platform.openai.com, developers.openai.com) are Cloudflare-fronted
  # and return inconsistent 403/404 responses to non-browser/CI requests depending on
  # path, even with a browser User-Agent; the pages resolve fine in a real browser.
  "platform\\.openai\\.com",
  "developers\\.openai\\.com",
  # luigi.readthedocs.io (intermittent 502 Bad Gateway in CI)
  "luigi\\.readthedocs\\.io",
  # tldp.org (intermittent 502 Bad Gateway in CI; sibling exit-code references
  # like gnu.org, man.openbsd.org, and refspecs.linuxfoundation.org are excluded for the same reason)
  "tldp\\.org",
  # no-color.org (intermittent connection failures / unreachable from CI runners;
  # it is the canonical NO_COLOR spec site referenced from the help-system and
  # io-handling PRDs, and resolves in a real browser)
  "no-color\\.org",
  # bixense.com (intermittent 503 Service Unavailable from CI runners; it is the
  # canonical CLICOLOR spec site referenced alongside NO_COLOR in the help-system
  # PRD, and resolves fine outside CI)
  "bixense\\.com",
  # Algolia DocSearch docs (intermittent timeouts from CI runners)
  "docsearch\\.algolia\\.com",
  # Open Group POSIX specs (intermittent timeouts from CI runners)
  "pubs\\.opengroup\\.org",
  # Pact docs (intermittent timeouts from CI runners)
  "docs\\.pact\\.io",
  # google-gemini/gemini-cli repo deep-links intermittently return 502 Bad Gateway
  # from GitHub's gateway in CI; the pages are valid and load in a browser.
  "github\\.com/google-gemini/gemini-cli",
  # gruntwork-io/terragrunt repo deep-links intermittently return 502 Bad Gateway
  # from GitHub's gateway in CI; the pages are valid and load in a browser.
  "github\\.com/gruntwork-io/terragrunt",
  # This specific older release tag page intermittently returns 500 Internal
  # Server Error from GitHub's gateway in CI; the page is valid and loads in
  # a browser (verified via `gh api repos/cloudposse/atmos/releases/tags/v1.203.0`).
  "github\\.com/cloudposse/atmos/releases/tag/v1\\.203\\.0",
  # NTIA's 2021 SBOM minimum-elements report is authoritative, but its TLS
  # chain is not trusted by GitHub-hosted runners. It resolves locally and in
  # browsers; keep the citation while excluding only this known-valid URL.
  "ntia\\.gov/report/2021/minimum-elements-software-bill-materials-sbom",
  # Otelic (intermittent "Connection reset by peer" from CI runners; the page
  # returns 200 and loads fine outside CI, verified via curl).
  "otelic\\.com",
  # Docker's docs (CloudFront-fronted) intermittently reset connections from
  # CI runners; the page 301-redirects then returns 200 outside CI, verified
  # via curl.
  "docs\\.docker\\.com",
  # These two blob-file deep links intermittently return 404 from GitHub's
  # gateway in CI even though the files exist on their repo's default branch;
  # both verified to return 200 outside CI via curl.
  "github\\.com/github/github-mcp-server/blob/main/docs/installation-guides/install-gemini-cli\\.md",
  "github\\.com/99designs/aws-vault/blob/master/USAGE\\.md",
  # This PDF intermittently times out from CI runners across multiple docs
  # referencing it; verified to return 200 outside CI via curl.
  "cis\\.upenn\\.edu/~bcpierce/papers/diff3-short\\.pdf",
]