Skip to content

docs(github-actions): add opt-in understand-quickly publish snippet #1563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
amacsmith wants to merge 2 commits into from
+54 −0
Closed

docs(github-actions): add opt-in understand-quickly publish snippet #1563

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
82945bf
docs(github-actions): add opt-in understand-quickly publish snippet
amacsmith May 10, 2026
b767ff7
docs(github-actions): address bot-review feedback on uq-publish snippet
amacsmith May 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions website/client/src/en/guide/github-actions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,3 +126,57 @@ jobs:
```

See the [complete workflow example](https://github.com/yamadashy/repomix/blob/main/.github/workflows/pack-repository.yml).

## Publishing to the understand-quickly registry

[`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 and only runs for public repos (the body is fetched from `raw.githubusercontent.com`). The workflow packs with Repomix, commits the output to a dedicated `understand-quickly` branch (so the URL is reachable), then publishes a small JSON pointer pinned to that commit SHA. Drop this into `.github/workflows/understand-quickly-publish.yml`:

```yaml
name: understand-quickly publish
on:
push:
branches: [main]
jobs:
publish:
runs-on: ubuntu-latest
permissions: { contents: write } # needs write to commit packed output
steps:
- uses: actions/checkout@v4
- uses: yamadashy/repomix/.github/actions/repomix@main # consider pinning @<sha>
with: { output: repomix-output.xml, style: xml }
- name: Commit packed output to understand-quickly branch
env:
REPO: ${{ github.repository }}
run: |
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git checkout --orphan understand-quickly
git rm -rf --cached . >/dev/null 2>&1 || true
git add -f repomix-output.xml
git commit -m "chore(uq): publish $(date -u +%Y-%m-%dT%H:%M:%SZ)"
git push --force origin understand-quickly
echo "UQ_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
- name: Build bundle@1 sidecar
env:
REPO: ${{ github.repository }}
SHA: ${{ env.UQ_SHA }}
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',generated_at:new Date().toISOString(),
byte_count:b,token_estimate:Math.round(b/4),format:'xml'},
content_url:\`https://raw.githubusercontent.com/\${process.env.REPO}/\${process.env.SHA}/repomix-output.xml\`
},null,2));"
Comment on lines +169 to +174
Comment on lines +161 to +174
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
- 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));"

- uses: looptech-ai/uq-publish-action@v0.1.0 # consider pinning @<sha>
with:
graph-path: repomix-output.bundle.json
format: bundle@1
token: ${{ secrets.UNDERSTAND_QUICKLY_TOKEN }}
```

Set `UNDERSTAND_QUICKLY_TOKEN` to a fine-grained PAT with `Repository dispatches: write` on `looptech-ai/understand-quickly` only. Register your repo once via [`npx @understand-quickly/cli add`](https://github.com/looptech-ai/understand-quickly#add-a-repo) or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html); subsequent pushes auto-refresh. See the [protocol](https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md) and [DATA-LICENSE.md](https://github.com/looptech-ai/understand-quickly/blob/main/DATA-LICENSE.md) for the data-grant semantics — submission is opt-in, gated on the secret being set, and only suitable for public repos.