docs: add opt-in understand-quickly publish workflow#577
Conversation
Adds docs/publishing.md describing how users can opt-in to publish their digest to the understand-quickly registry. The workflow is gated on UNDERSTAND_QUICKLY_TOKEN — no secret, no network call. No CLI changes, no behavior changes — docs only.
There was a problem hiding this comment.
Pull request overview
Documents an opt-in GitHub Actions workflow for publishing gitingest-generated digests to the external looptech-ai/understand-quickly registry, keeping the integration entirely in CI and leaving the CLI/runtime unchanged.
Changes:
- Add
docs/publishing.mddescribing the registry, setup steps, and a drop-in publish workflow snippet. - Add a README pointer linking users to the new publishing documentation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds a link directing users to the new opt-in publishing guide. |
| docs/publishing.md | Introduces end-to-end documentation and an example workflow to generate and publish a bundle@1 sidecar + digest. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| permissions: { contents: read } | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - run: pip install gitingest && gitingest . -o digest.txt |
| 'generated_at': '$(date -u +%Y-%m-%dT%H:%M:%SZ)', | ||
| 'file_count': 0, 'byte_count': b, 'token_estimate': b // 4, | ||
| 'format': 'plaintext'}, | ||
| 'content_url': f'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/digest.txt' |
| permissions: { contents: read } | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - run: pip install gitingest && gitingest . -o digest.txt |
- Add commit step so content_url actually resolves (was pointing to raw.githubusercontent.com for an uncommitted digest -> 404). - Pin content_url to the commit SHA via env var instead of github.ref_name (immutable + script-injection safe). - Use actions/setup-python + python -m pip for reproducibility. - Use timezone-aware datetime; replace bogus f-string with proper heredoc. - Drop hard-coded placeholder fields (tool_version:'latest', file_count:0). - Note the workflow is only suitable for public repos.
|
Pushed 6e8f395 addressing the Copilot review:
Action pinning: noted inline that real workflows should pin to a SHA; left floating refs in the docs snippet for readability — happy to switch if you'd prefer. |
|
Quick update from upstream — the registry just hit
The PR is rebased and ready. Happy to address any further feedback whenever you have a moment. |
Why
looptech-ai/understand-quicklyis a public, machine-readable registry of code-knowledge and code-context artifacts. It indexes Gitingest digests through itsbundle@1format — a tiny JSON pointer plus a raw URL to the digest body — so AI agents (Claude, Codex, Cursor via MCP) can resolve a repo URL to its Gitingest digest. The registry stores no bodies; the digest stays in the user's repo and is fetched fromraw.githubusercontent.com.This PR is docs-only. It documents the opt-in workflow for Gitingest users who want their digest to land in the registry. No CLI changes, no runtime changes.
What changes
docs/publishing.md— explains the registry, one-time setup, and a drop-in.github/workflows/understand-quickly-publish.ymlsnippet (~30 lines) that chainsgitingestwith thelooptech-ai/uq-publish-action@v0.1.0Marketplace Action. The snippet builds a small bundle@1 sidecar (file size, generated_at, content_url) and hands it off to publish.README.md: a one-line pointer at the bottom of "Command line usage" linking todocs/publishing.md.Opt-in / no-op
Submission is gated entirely on the user setting
UNDERSTAND_QUICKLY_TOKEN(a fine-grained PAT scoped tolooptech-ai/understand-quicklyonly withRepository dispatches: write). Without the secret, the publish action only stamps metadata locally and exits cleanly. Without the workflow file, nothing changes.Why no CLI change
The flow is entirely orchestrated in Actions: Gitingest already emits
digest.txt, the Marketplace Action builds the bundle@1 sidecar and posts the dispatch. Keeping the integration on the CI side means no new flag in the CLI surface, no test churn, and no behavior change for anyone not opting in.Test plan
docs/publishing.md, two-line README pointer).pyproject.tomlchanges, no Python source touched.Notes
DATA-LICENSE.mdand protocol §12 — opt-in, gated on the secret, never invisible.Links