Source: ViewEdit

Notify the docs hub of link changes

Live site: +.

Multi-repo hubs rebuild when a content repo pokes the playbook repo — see Auto-rebuild when content sources or extensions update.

Link-cache invalidation adds optional surgical recheck hints for @antora-supplemental/link-validator (env LINK_VALIDATOR_INVALIDATE_*, v0.2.2+) while the hub still runs a full Antora generate and GitHub Pages deploy.

Agent skill: docs-hub-link-invalidate (dev-centr/agent-rules).

Hub subscriber (this repo)

Workflow: .github/workflows/deploy.yml listens for:

  • push to main

  • pull_request (build only)

  • workflow_dispatch

  • repository_dispatch types docs-source-updated, extension-updated, link-cache-invalidate

On link-cache-invalidate, the build maps github.event.client_payload to:

| Payload field | Build env | Notes | |===|===|=== | sources | LINK_VALIDATOR_INVALIDATE_SOURCES | Comma-separated string or JSON array | | urls | LINK_VALIDATOR_INVALIDATE_URLS | Comma-separated string or JSON array | | ref | checkout ref | Default main when omitted | | source, sha | (log context) | Calling repo |

Deploy runs for repository_dispatch even when the hub checkout ref is not refs/heads/main.

Fire a dispatch with gh

Org secret DOCS_HUB_DISPATCH_TOKEN: token with permission to create repository_dispatch on antora-supplemental/docs.

gh api repos/antora-supplemental/docs/dispatches \
  -f event_type=link-cache-invalidate \
  -f client_payload[source]=antora-supplemental/asciidoc-interactive \
  -f client_payload[ref]=main \
  -f client_payload[sha]=$(git rev-parse HEAD) \
  -f client_payload[sources]=docs/modules/ROOT/pages/index.adoc

Reusable caller workflow (org default)

Path: antora-supplemental/.github/.github/workflows/docs-hub-link-cache-invalidate-dispatch.yml

jobs:
  notify:
    uses: antora-supplemental/.github/.github/workflows/docs-hub-link-cache-invalidate-dispatch.yml@main
    secrets:
      DOCS_HUB_DISPATCH_TOKEN: ${{ secrets.DOCS_HUB_DISPATCH_TOKEN }}
    with:
      hub_repo: antora-supplemental/docs

Exemplar thin caller: antora-supplemental/asciidoc-interactive/.github/workflows/notify-docs-hub-link-invalidate.yml.

Related