🤖 Agente autônomo
A própria ferramenta se automelhorando. Você rotula uma issue com polypus-go e o Polypus — rodando a si mesmo num runner do GitHub Actions — implementa a mudança, valida na CI, abre o PR e, ao mergear, publica a nova versão no npm. O ciclo issue → código → release fecha sozinho, com modelos baratos e guard-rails de segurança.
🇬🇧 In short: label an issue polypus-go and Polypus runs itself in CI to implement it, gates on typecheck/build/test, opens a release-ready PR, and — once you merge — publishes the patched version to npm. This page documents the flow, the guard-rails and how to set up the POLYPUS_PR_TOKEN.
🔒 Aprovação por comentário (só o admin)
Ao rotular com polypus-go, o Polypus primeiro estima
o esforço/custo e comenta na issue — e não implementa nada até o
dono do repositório comentar /polypus approve. Só o owner
(admin) pode aprovar (verificado por author_association == OWNER). Sem PAT/Environment extra:
o comentário é o gate.
O fluxo, ponta a ponta
Três peças trabalham em sequência: o workflow agent.yml (implementa e prepara o release),
o seu merge (único toque humano — respeita a branch protection) e o
auto-release.yml + release.yml (publicam no npm).
Rotula a issue com polypus-go
Opt-in por issue. Mantenha também a label accepted para o PR gerado passar no require-issue.
Implementa headless
Monta a tarefa da issue + .poly/agents.md/context.md/rules.md e roda polypus run --mode bypass --verify --json --budget com um modelo barato.
Guard-rails
Recusa abrir PR se achar segredo no diff; roda só no repositório próprio.
Gate de CI
typecheck + build + test precisam passar. Se falhar, nada de PR.
Prepara o release
scripts/prepare-release.mjs faz o bump patch + CHANGELOG e regenera o context.md — o PR já vem release-ready.
Abre o PR feat: … (Closes #N)
Da branch polypus/issue-N. Usa o POLYPUS_PR_TOKEN; se faltar, comenta o link da branch na issue (nunca falha vermelho).
Revisa e dá merge
O único gate humano. É aqui que você decide se o que o agente fez vai pro mundo.
Cria o GitHub Release vX.Y.Z
Dispara ao mergear um PR de branch polypus/issue-*. Usa o POLYPUS_PR_TOKEN para que o Release acione o passo seguinte.
Publica no npm
Valida versão = tag, roda typecheck/test/build e npm publish --provenance. A nova versão fica em @gaberrb/polypus.
Em uma linha
Configuração
Quatro coisas. A label, a chave do modelo, o token que abre o PR/publica, e (opcional) o modelo e o orçamento.
polypus-go
gh label create polypus-go --color 5be4b1 \
--description "Polypus implementa esta issue automaticamente"Aplique-a (junto de accepted) na issue que quiser que o agente implemente.
OPENROUTER_API_KEY — a chave do modelo que escreve o código.
gh secret set OPENROUTER_API_KEY --body "sk-or-v1-..."POLYPUS_PR_TOKEN — um Personal Access Token (PAT) com escopo repo.
É o que permite abrir o PR e publicar no npm de forma autônoma. Crie em github.com/settings/tokens:
# 1) Fine-grained token (recomendado): Settings → Developer settings →
# Personal access tokens → Fine-grained tokens → Generate new token
# - Repository access: só o repo GaberRB/polypus
# - Permissions: Contents = Read/Write, Pull requests = Read/Write
# (ou um classic token com o escopo `repo`)
# 2) registre como secret do repositório:
gh secret set POLYPUS_PR_TOKEN --body "github_pat_..."gh variable set POLYPUS_AGENT_MODEL --body "deepseek/deepseek-chat-v3-0324"
gh variable set POLYPUS_BUDGET_USD --body "0.50"Sem isso, o padrão é DeepSeek V3 e US$0,50 por execução. Pense em modelos com bom custo/qualidade (DeepSeek, Qwen, GLM…).
Por que o POLYPUS_PR_TOKEN é obrigatório para o npm?
Um GitHub Release criado pelo GITHUB_TOKEN padrão não dispara outros workflows
(regra do GitHub para evitar loops). Ou seja: sem um PAT, o auto-release.yml até cria o Release,
mas o release.yml (o que publica no npm) nunca roda. Com o PAT, o Release
dispara o publish normalmente. O auto-release.yml avisa claramente se o token estiver faltando.
Sem o PAT, nada quebra: o agente ainda implementa, valida e empurra a branch — e, se não conseguir abrir o PR, comenta o link de comparação na issue. Você só não ganha a publicação 100% automática.
Exemplo
# 1. Crie uma issue descrevendo o que quer (quanto mais claro, melhor)
# 2. Rotule-a:
gh issue edit 123 --add-label accepted --add-label polypus-go
# → agent.yml dispara, implementa com DeepSeek, passa no gate de CI,
# faz o bump (ex.: 0.4.16 → 0.4.17) e abre:
# "feat: <título da issue> (Closes #123)" na branch polypus/issue-123
# 3. Você revisa o PR e dá merge
gh pr merge <n> --squash
# → auto-release.yml cria v0.4.17 → release.yml publica:
# npm i -g @gaberrb/polypus@0.4.17Guard-rails
🏠 Repo próprio
O job só roda em GaberRB/polypus — forks não disparam a automação.
🔑 Scan de segredos
Antes de abrir o PR, o diff é varrido por chaves (AWS, GitHub, OpenAI, blocos de chave privada). Achou? Aborta.
🧪 Gate de CI
Sem typecheck + build + test verdes, não há PR. Código quebrado não chega ao npm.
💸 Orçamento
--budget corta a execução ao atingir o teto em USD, evitando surpresas de custo.
🙋 Você no comando
O merge é o único caminho até o npm — nenhuma linha não-revisada publica sem o seu OK.
🔁 Autocorreção
O --verify devolve falhas de teste ao agente até passar ou esgotar as tentativas.
🌱 A ferramenta cuidando da própria evolução
Esta automação é o Polypus usando o Polypus: o mesmo loop ReAct, as mesmas tools, as mesmas permissões que você usa no dia a dia — agora apontados para o próprio repositório. Cada issue aceita vira, potencialmente, uma melhoria publicada — com humano na curva apenas onde importa: o merge. Inclusive esta página faz parte dessa história: documentar o agente é parte de deixá-lo crescer com cuidado.