docs(github-actions): add opt-in understand-quickly publish snippet#1563
docs(github-actions): add opt-in understand-quickly publish snippet#1563amacsmith wants to merge 2 commits into
Conversation
Adds a 'Publishing to the understand-quickly registry' subsection to the existing GitHub Actions guide. The snippet is opt-in (gated on the user setting UNDERSTAND_QUICKLY_TOKEN); without the secret, the registry's publish action only stamps metadata locally and exits cleanly. No CLI changes, no behavior changes — docs only.
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughAdded documentation to the GitHub Actions guide describing optional publishing of Repomix output to the understand-quickly registry. Includes a complete example workflow that generates repomix-output.xml, creates a bundle@1 sidecar JSON, and publishes via looptech-ai/uq-publish-action with secret-gated token authentication. Changesunderstand-quickly Registry Publishing Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/client/src/en/guide/github-actions.md`:
- Line 158: Update the example `content_url` to use an immutable commit SHA
instead of the branch name: replace the use of `${{ github.ref_name }}` in the
`content_url` string with `${{ github.sha }}` so published registry entries
point to the exact commit; locate the
`content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{
github.ref_name }}/repomix-output.xml'` example and modify it accordingly.
- Line 147: Replace the floating action refs with pinned commit SHAs: locate the
workflow lines that read "uses: yamadashy/repomix/.github/actions/repomix@main"
(and the other "uses:" occurrence around line 160) and update both to use the
full commit SHA of the exact upstream commit you want to run (e.g.,
".github/actions/repomix@<FULL_COMMIT_SHA>"). Ensure both occurrences are
updated so the workflow uses immutable SHAs rather than "@main" or tag refs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 10cf1170-6c9a-47c2-be4f-6282bb082f02
📒 Files selected for processing (1)
website/client/src/en/guide/github-actions.md
| permissions: { contents: read } | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: yamadashy/repomix/.github/actions/repomix@main |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and read it
fd -t f "github-actions.md" website/Repository: yamadashy/repomix
Length of output: 760
🏁 Script executed:
# Read the specific file with line numbers to verify lines 147 and 160
if [ -f "website/client/src/en/guide/github-actions.md" ]; then
wc -l "website/client/src/en/guide/github-actions.md"
fiRepository: yamadashy/repomix
Length of output: 111
🏁 Script executed:
# Get content around lines 147 and 160
if [ -f "website/client/src/en/guide/github-actions.md" ]; then
echo "=== Lines 140-155 ===" && sed -n '140,155p' "website/client/src/en/guide/github-actions.md"
echo ""
echo "=== Lines 155-165 ===" && sed -n '155,165p' "website/client/src/en/guide/github-actions.md"
fiRepository: yamadashy/repomix
Length of output: 1226
Pin GitHub Actions by commit SHA in this publish example.
This workflow uses a secret token (secrets.UNDERSTAND_QUICKLY_TOKEN) with GitHub Actions, making it a supply-chain sensitive context. Floating refs (@main) and tag refs (@v0.1.0) instead of full commit SHAs increase the risk of malicious code injection. Documentation should model secure defaults using commit SHAs for both actions on lines 147 and 160.
Proposed doc hardening
- - uses: yamadashy/repomix/.github/actions/repomix@main
+ - uses: yamadashy/repomix/.github/actions/repomix@<full_commit_sha>- - uses: looptech-ai/uq-publish-action@v0.1.0
+ - uses: looptech-ai/uq-publish-action@<full_commit_sha>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/client/src/en/guide/github-actions.md` at line 147, Replace the
floating action refs with pinned commit SHAs: locate the workflow lines that
read "uses: yamadashy/repomix/.github/actions/repomix@main" (and the other
"uses:" occurrence around line 160) and update both to use the full commit SHA
of the exact upstream commit you want to run (e.g.,
".github/actions/repomix@<FULL_COMMIT_SHA>"). Ensure both occurrences are
updated so the workflow uses immutable SHAs rather than "@main" or tag refs.
| format:'bundle@1', | ||
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | ||
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, | ||
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml' |
There was a problem hiding this comment.
Use an immutable content_url (commit SHA), not branch name.
github.ref_name points to a moving branch tip, so previously published registry entries may later resolve to different content. Use ${{ github.sha }} in the raw URL so each published bundle is permanently tied to the exact commit.
Proposed doc snippet update
- content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml'
+ content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.sha }}/repomix-output.xml'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml' | |
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.sha }}/repomix-output.xml' |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/client/src/en/guide/github-actions.md` at line 158, Update the
example `content_url` to use an immutable commit SHA instead of the branch name:
replace the use of `${{ github.ref_name }}` in the `content_url` string with
`${{ github.sha }}` so published registry entries point to the exact commit;
locate the `content_url:'https://raw.githubusercontent.com/${{ github.repository
}}/${{ github.ref_name }}/repomix-output.xml'` example and modify it
accordingly.
There was a problem hiding this comment.
Pull request overview
Adds documentation describing an opt-in GitHub Actions workflow that chains Repomix output with publishing metadata to the external looptech-ai/understand-quickly registry (no CLI/runtime changes).
Changes:
- Adds a new “Publishing to the understand-quickly registry” subsection to the GitHub Actions guide.
- Provides an example workflow that generates Repomix output, builds a
bundle@1JSON sidecar, and invokeslooptech-ai/uq-publish-action. - Documents the required
UNDERSTAND_QUICKLY_TOKENsecret and links to registry/protocol/licensing docs.
| fs.writeFileSync('repomix-output.bundle.json', JSON.stringify({ | ||
| format:'bundle@1', | ||
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | ||
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, | ||
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml' | ||
| },null,2));" |
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | ||
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, |
|
|
||
| [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public, machine-readable registry of code-knowledge and code-context artifacts. It indexes Repomix output through its [`bundle@1`](https://github.com/looptech-ai/understand-quickly/blob/main/schemas/bundle@1.json) format so AI agents (Claude, Codex, Cursor via MCP) can resolve a repo URL to its packed-context bundle. | ||
|
|
||
| Publishing is opt-in. Drop this workflow into `.github/workflows/understand-quickly-publish.yml` to pack with Repomix and publish a small JSON pointer (the body stays in your repo and is fetched from `raw.githubusercontent.com`): |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation and a GitHub Actions workflow example for publishing Repomix output to the understand-quickly registry. The feedback highlights that the generated output file needs to be committed to the repository for the provided content URL to be valid, requiring a permission update to contents: write. Additionally, it is recommended to use environment variables instead of direct interpolation in the shell script to follow security best practices.
| jobs: | ||
| publish: | ||
| runs-on: ubuntu-latest | ||
| permissions: { contents: read } |
There was a problem hiding this comment.
The workflow generates repomix-output.xml but does not commit it to the repository. Since the content_url (line 158) points to raw.githubusercontent.com, the file must be present in the repository for the URL to be valid. To support this, you should update the permissions to contents: write and add a step to commit and push the generated file.
| permissions: { contents: read } | |
| permissions: { contents: write } |
| - name: Build bundle@1 sidecar | ||
| run: | | ||
| node -e " | ||
| const fs=require('fs'); | ||
| const b=fs.statSync('repomix-output.xml').size; | ||
| fs.writeFileSync('repomix-output.bundle.json', JSON.stringify({ | ||
| format:'bundle@1', | ||
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | ||
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, | ||
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml' | ||
| },null,2));" |
There was a problem hiding this comment.
It is a security best practice to use environment variables instead of directly interpolating GitHub context variables (like ${{ github.repository }}) into shell scripts. This prevents potential script injection and handles special characters more safely. Additionally, using an environment variable for the output filename makes the script more maintainable if the filename changes in the future.
| - name: Build bundle@1 sidecar | |
| run: | | |
| node -e " | |
| const fs=require('fs'); | |
| const b=fs.statSync('repomix-output.xml').size; | |
| fs.writeFileSync('repomix-output.bundle.json', JSON.stringify({ | |
| format:'bundle@1', | |
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | |
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, | |
| content_url:'https://raw.githubusercontent.com/${{ github.repository }}/${{ github.ref_name }}/repomix-output.xml' | |
| },null,2));" | |
| - name: Build bundle@1 sidecar | |
| env: | |
| REPO: ${{ github.repository }} | |
| REF: ${{ github.ref_name }} | |
| OUTPUT_FILE: repomix-output.xml | |
| run: | | |
| node -e " | |
| const fs=require('fs'); | |
| const b=fs.statSync(process.env.OUTPUT_FILE).size; | |
| fs.writeFileSync('repomix-output.bundle.json', JSON.stringify({ | |
| format:'bundle@1', | |
| manifest:{tool:'repomix',tool_version:'latest',generated_at:new Date().toISOString(), | |
| file_count:0,byte_count:b,token_estimate:Math.round(b/4),format:'xml'}, | |
| content_url:'https://raw.githubusercontent.com/' + process.env.REPO + '/' + process.env.REF + '/' + process.env.OUTPUT_FILE | |
| },null,2));" |
- Add commit step so content_url actually resolves (was pointing to raw.githubusercontent.com for an uncommitted artifact -> 404). - Pin content_url to the commit SHA instead of github.ref_name for immutable bundles. - Move github context out of inline shell into env vars (script-injection safety). - Drop hard-coded placeholder fields (tool_version:'latest', file_count:0). - Note the workflow is only suitable for public repos.
|
Pushed b767ff7 addressing the CodeRabbit / Copilot / gemini-code-assist findings:
Left action refs as floating in the example ( |
|
@amacsmith |
Why
looptech-ai/understand-quicklyis a public, machine-readable registry of code-knowledge and code-context artifacts. It indexes Repomix output through itsbundle@1format — a tiny JSON pointer plus a raw URL to the packed body — so AI agents (Claude, Codex, Cursor via MCP) can resolve a repo URL to its Repomix-packed context. The registry stores no bodies; the XML/markdown stays in the user's repo.This PR documents the opt-in workflow for Repomix users who want their packed output to land in the registry. No CLI changes, no runtime changes — only the GitHub Actions guide gets a new subsection.
What changes
website/client/src/en/guide/github-actions.md: appends a "Publishing to the understand-quickly registry" subsection (~30 lines of YAML + ~5 lines of prose) showing how to chain the existingyamadashy/repomix/.github/actions/repomixaction with the newlooptech-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.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: Repomix already emits the packed body, 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
package.json/biomechanges, no lint impact.Notes
DATA-LICENSE.mdand protocol §12 — opt-in, gated on the secret, never invisible.Links