understand-quickly publish Action

A drop-in composite Action that publishes a code-knowledge graph to the looptech-ai/understand-quickly registry. Use it from any tool that emits a JSON graph — Understand-Anything, GitNexus, code-review-graph, repo-context bundles, or your own format.

Quickstart

Add to your release/build workflow after the step that generates the graph:

- uses: looptech-ai/uq-publish-action@v0.1.0
  with:
    graph-path: '.understand-anything/knowledge-graph.json'
    format: 'understand-anything@1'
    tool-version: ${{ github.ref_name }}
    token: ${{ secrets.UNDERSTAND_QUICKLY_TOKEN }}

That's it. The Action will:

1. Inject metadata.{tool, tool_version, generated_at, commit} into the graph file (so the registry can do drift detection).
2. POST a repository_dispatch (event_type=sync-entry) at the registry, asking it to resync your entry now instead of waiting for the nightly run.

If token is unset, the dispatch step no-ops with a warning — the metadata is still stamped, and the next nightly sync will pick the change up.

Inputs

Name	Required	Default	Description
graph-path	yes	—	Path to the generated graph JSON file. Must be valid JSON with an object root.
format	yes	—	Registered format slug (understand-anything@1, gitnexus@1, code-review-graph@1, bundle@1, generic@1, or your own).
tool-version	no	unknown	Stamped into metadata.tool_version. Pass a release tag, git describe, semver, etc.
registry	no	looptech-ai/understand-quickly	Override only when targeting a fork or test registry.
token	no	(empty)	Fine-grained PAT scoped to Repository dispatches: write on registry. Empty = stamp metadata, skip dispatch.
stamp-metadata	no	true	Set to false to skip the metadata-stamping step (e.g. if your tool already writes the metadata block itself).

Token setup

UNDERSTAND_QUICKLY_TOKEN is a fine-grained GitHub PAT with a single permission:

• Repository access: looptech-ai/understand-quickly only.
• Permissions: Contents: read, Metadata: read, Repository dispatches: write. Nothing else.

Add it as a repo secret in Settings → Secrets and variables → Actions, then reference as ${{ secrets.UNDERSTAND_QUICKLY_TOKEN }} in the workflow.

The registry only listens for event_type=sync-entry; the token gives no other access.

What gets stamped

After the action runs, the metadata block at the root of your graph JSON looks like:

{
  "metadata": {
    "commit": "1234567890abcdef1234567890abcdef12345678",
    "generated_at": "2026-05-09T12:00:00.000Z",
    "tool": "understand-anything",
    "tool_version": "0.4.2"
  }
}

Existing metadata.* fields the producer already wrote are preserved verbatim — the action only fills missing keys. Output is sorted and indented for clean diffs.

The action does not touch nodes, edges, manifest, or any other top-level field.

Examples

See docs/examples/ for full workflows:

• nodejs.yml — Node-based generator (e.g. Understand-Anything, GitNexus).
• python.yml — Python generator (e.g. code-review-graph).
• manual.yml — Skip generation, publish a hand-maintained graph.

Troubleshooting

Dispatch unauthorized (HTTP 401) / (HTTP 403) The token is missing the Repository dispatches: write permission, has expired, or is scoped to the wrong repo. Generate a fresh fine-grained PAT with only that permission on looptech-ai/understand-quickly.

Dispatch payload rejected (HTTP 422) ... not registered yet The dispatch was accepted but the registry's sync workflow logged that your repo id (<owner>/<repo>) isn't in registry.json. Run npx @understand-quickly/cli add once, or use the wizard. After the entry is merged, future runs of this Action will succeed.

Registry repo or dispatch endpoint not found (HTTP 404) The registry input points at a repo that doesn't exist or that the token can't see. Default is looptech-ai/understand-quickly; only override for forks or testing.

Action ran but my entry didn't refresh Check the registry's sync workflow runs — they're public. Each run logs per-entry results.

Security

• The token is read from an inputs.token slot and is never echoed to logs. The dispatch step writes the response body to a tempfile and deletes it on exit.
• All shell variables are quoted; payload is built with printf rather than string interpolation.
• The action only needs network access to api.github.com. No code from your graph is executed.
• Failures soft-fail with ::warning:: annotations so a misconfigured registry never breaks your release pipeline.

Versioning

Pin to a specific tag (@v0.1.0) or to the major (@v0) for compatible updates. Tags are signed releases.

License

MIT — see LICENSE.

Contributing

Issues and PRs welcome. The integration protocol this Action implements lives at looptech-ai/understand-quickly/docs/integrations/protocol.md.