Integração com CI
Quais comandos são baratos o bastante para rodar a cada commit, quais precisam de uma chave e como quebrar o build quando o handbook entra em deriva.
O que custa o quê
| Comando | Precisa de chave? | Determinístico? | Rode… |
|---|---|---|---|
analyze | ❌ | ✅ | a cada commit |
render | ❌ | ✅ | a cada commit |
skill | ❌ | ✅ | a cada commit |
validate | ❌ | ✅ | a cada commit |
config --check | ❌ | ✅ | a cada commit |
apply / rollback | ❌ | ✅ | sob demanda |
generate | ✅ | ❌ | na main, ou de forma agendada |
resync | ✅ | ❌ | na main |
plan | ✅ | ❌ | sob demanda |
Cinco deles são gratuitos. Um workflow de pull request que os execute não custa nada e pega problemas reais.
O job gratuito de pull request
name: handbook check
on: [pull_request]
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: pnpm }
- run: pnpm install --frozen-lockfile
- run: pnpm build
# 1. Configuration is valid — catches a typo'd variable before it costs a run.
- run: node packages/cli/dist/main.js config --check --command generate
# 2. The call graph still builds, and the file count has not collapsed.
- name: analyze
run: |
node packages/cli/dist/main.js analyze --source . --work work/self > stats.json
cat stats.json
test "$(jq .files stats.json)" -gt 10
# 3. The committed SKILL package is still structurally valid, and still fresh.
- name: validate the skill
run: node packages/cli/dist/main.js validate --skill skills/self --source .O validate sai com 2 quando o skill entrou em deriva. Decida se isso deve quebrar
o build ou apenas emitir um aviso:
- run: node packages/cli/dist/main.js validate --skill skills/self --source .
continue-on-error: true # warn; schedule a resync instead of blocking the PRRegenerando na main
name: handbook resync
on:
push:
branches: [main]
workflow_dispatch:
concurrency:
group: handbook-resync
cancel-in-progress: false # never interleave two runs on the same work dir
jobs:
resync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 2 }
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: pnpm }
- run: pnpm install --frozen-lockfile && pnpm build
- name: assemble the resync case
run: |
mkdir -p case
rsync -a --exclude .git --exclude node_modules --exclude work ./ case/edited/
git diff HEAD~1 > case/change.diff
- name: resync
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: node packages/cli/dist/main.js resync --case case --work work/self
- name: repackage and validate
run: |
node packages/cli/dist/main.js skill \
--handbook work/self/handbook --out skills/self --name self \
--work work/self --source . --agent-dir work/self/handbook/agent
node packages/cli/dist/main.js validate --skill skills/self --source .
- uses: peter-evans/create-pull-request@v6
with:
branch: chore/handbook-resync
title: 'docs: roll the handbook forward'
commit-message: 'docs: roll the handbook forward'Dois detalhes que importam:
concurrencycomcancel-in-progress: false. Um lock garante uma execução por diretório de trabalho; duas execuções de CI sobrepostas apenas fariam uma delas falhar.- Abra um PR em vez de dar push. Um handbook regenerado é um diff que vale a pena ler.
Publicando o site HTML
name: publish handbook
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
publish:
runs-on: ubuntu-latest
environment: github-pages
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with: { node-version: 22, cache: pnpm }
- run: pnpm install --frozen-lockfile && pnpm build
- run: |
node packages/cli/dist/main.js render \
--work work/self --title "Self Handbook" \
--html --html-single --agent-site --llms-txt \
--source-base-url https://github.com/${{ github.repository }}/blob/${{ github.sha }}
- run: cp work/self/handbook/llms*.txt work/self/handbook/html/
- uses: actions/upload-pages-artifact@v3
with: { path: work/self/handbook/html }
- uses: actions/deploy-pages@v4A renderização é gratuita e determinística, então isto pode rodar a cada push. Apontar
--source-base-url para ${{ github.sha }} em vez de main faz com que cada link do
handbook publicado aponte para exatamente o código a partir do qual ele foi renderizado.
Comitando o diretório de trabalho
São apenas JSON e YAML, então comitá-lo é uma escolha legítima:
A favor — o diff de uma regeneração é revisável, o render não precisa de chave no CI
e o validate passa a ter algo com que comparar.
Contra — phase2/cards/ fica grande em um repositório grande, e a prosa das fichas de
arquivo oscila entre versões de modelo.
Um bom meio-termo: comite skills/<name>/ (pequeno, e é o que os agentes consomem) e
deixe work/ no gitignore (grande, e regenerável).
Cache entre execuções
- uses: actions/cache@v4
with:
path: work/self/phase3/cache
key: handbook-cache-${{ hashFiles('**/*.ts', '**/*.py') }}
restore-keys: handbook-cache-O cache da Phase 3 é chaveado por hash de conteúdo, então restaurar um cache obsoleto é
seguro — ele simplesmente dá miss. Guardar em cache phase2/cards/ junto com --resume é
ainda mais eficaz quando poucos arquivos mudam a cada execução.
Falhando por deriva, deliberadamente
handbook validate --skill skills/api --source .
case $? in
0) echo "handbook is fresh" ;;
2) echo "::warning::handbook has drifted — a resync is due" ;;
*) exit 1 ;;
esacTrate o 2 como um sinal de agendamento, não como uma quebra de build. Um handbook
desatualizado é tarefa de manutenção; um handbook quebrado (saída 1) é um bug.