docs: add opt-in understand-quickly publish workflow#7
Open
amacsmith wants to merge 2 commits into
Open
Conversation
Adds PUBLISHING.md describing how users can opt-in to publish their codebase 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
Docs-only PR documenting an opt-in GitHub Actions workflow for publishing Codebase Digest output to the external looptech-ai/understand-quickly registry.
Changes:
- Add
PUBLISHING.mddescribing the registry, one-time setup, and a sample publishing workflow. - Add a
README.mdpointer linking users toPUBLISHING.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| README.md | Adds a link guiding users to the publishing documentation. |
| PUBLISHING.md | Introduces end-to-end documentation and a sample GitHub Actions workflow snippet for publishing. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+27
to
+40
| - run: pip install codebase-digest && cdigest . -o markdown -f digest.md | ||
| - name: Build bundle@1 sidecar | ||
| run: | | ||
| python -c " | ||
| import json, os, datetime | ||
| b = os.path.getsize('digest.md') | ||
| json.dump({ | ||
| 'format': 'bundle@1', | ||
| 'manifest': {'tool': 'codebase-digest', 'tool_version': 'latest', | ||
| 'generated_at': datetime.datetime.utcnow().isoformat() + 'Z', | ||
| 'file_count': 0, 'byte_count': b, 'token_estimate': b // 4, | ||
| 'format': 'markdown'}, | ||
| 'content_url': 'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/digest.md' | ||
| }, open('digest.bundle.json', 'w'), indent=2)" |
| permissions: { contents: read } | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - run: pip install codebase-digest && cdigest . -o markdown -f digest.md |
Comment on lines
+32
to
+37
| b = os.path.getsize('digest.md') | ||
| json.dump({ | ||
| 'format': 'bundle@1', | ||
| 'manifest': {'tool': 'codebase-digest', 'tool_version': 'latest', | ||
| 'generated_at': datetime.datetime.utcnow().isoformat() + 'Z', | ||
| 'file_count': 0, 'byte_count': b, 'token_estimate': b // 4, |
| json.dump({ | ||
| 'format': 'bundle@1', | ||
| 'manifest': {'tool': 'codebase-digest', 'tool_version': 'latest', | ||
| 'generated_at': datetime.datetime.utcnow().isoformat() + 'Z', |
|
|
||
| ## Workflow | ||
|
|
||
| Drop into `.github/workflows/understand-quickly-publish.yml`. It runs `cdigest`, writes a small `bundle@1` sidecar, then hands off to the [`looptech-ai/uq-publish-action`](https://github.com/looptech-ai/uq-publish-action) Marketplace Action. |
Comment on lines
+14
to
+15
| Drop into `.github/workflows/understand-quickly-publish.yml`. It runs `cdigest`, writes a small `bundle@1` sidecar, then hands off to the [`looptech-ai/uq-publish-action`](https://github.com/looptech-ai/uq-publish-action) Marketplace Action. | ||
|
|
- 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 instead of deprecated utcnow(). - Drop hard-coded placeholder fields (tool_version:'latest', file_count:0). - Note the workflow is only suitable for public repos. - Grammar fix in intro.
Author
|
Pushed 2a677a1 addressing the Copilot review:
|
Author
|
Quick update from upstream — the registry just hit
The PR is rebased and the merge state is clean. Happy to address any further feedback whenever you have a moment. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
looptech-ai/understand-quicklyis a public, machine-readable registry of code-knowledge and code-context artifacts. It indexes Codebase Digest output 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 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
cdigestusers who want their digest to land in the registry. No CLI changes, no runtime changes.What changes
PUBLISHING.md— explains the registry, one-time setup, and a drop-in.github/workflows/understand-quickly-publish.ymlsnippet (~30 lines) that runscdigest, builds a small bundle@1 sidecar (file size, generated_at, content_url, format), and hands it off to thelooptech-ai/uq-publish-action@v0.1.0Marketplace Action.README.md: a one-line pointer at the bottom of the "Usage" examples linking toPUBLISHING.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:
cdigestalready emits the digest, 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
PUBLISHING.md, two-line README pointer).setup.pychanges.Notes
DATA-LICENSE.mdand protocol §12 — opt-in, gated on the secret, never invisible.Links