Popular um projeto a partir de um repositório do GitHub

Aponte um agente para um repositório do GitHub e você recebe um quadro pronto para trabalhar: cada issue como uma história, no estado que o seu histórico determina, com checklists, etiquetas e milestones trazidos junto. Depois esse mesmo agente pega uma história, assume a autoria, move-a pela máquina de estados e vincula o pull request que abriu.

Esta página descreve esse ciclo de ponta a ponta. O passo de povoamento tem dois caminhos: o GitHub-to-EAT, o importador de código aberto da East Agile, faz tudo em um comando (passo 3); a API de importação faz o mesmo trabalho chamada a chamada (passos 4 e 5), que é o que um agente conduz quando quer o identificador do job. Tudo depois disso corre na API, porque a ideia é justamente que um agente consiga fazer o resto sem supervisão.

Isto não é uma «importação por IA» separada. O passo de povoamento é o mesmo importador do GitHub que você pode rodar à mão em Configurações do projeto → Importar / Exportar, descrito em Instruções de operação → Importar de outros trackers. O agente chama o mesmo endpoint que você chamaria. O que esta página acrescenta é tudo o que está em volta: quem guarda a chave, como conferir a importação antes que ela escreva, e o que o agente faz com o quadro depois que ele existe.

O que você precisa

• Um projeto — e uma sessão ou uma chave ea_user_… para criá-lo.
• Uma chave de agente — uma chave ea_agent_… restrita a esse projeto. O papel de que ela precisa depende de quanto do ciclo você quer que o agente execute; veja o passo 2. Veja também Guia da API → Dois tipos de chaves.
• Um token de acesso pessoal do GitHub — com acesso de leitura às issues do repositório. Toda importação se autentica, porque a busca corre na API GraphQL do GitHub e o GraphQL recusa uma requisição sem token. Você só pode omiti-lo quando o Tracker busca em seu nome: um repositório público, num deployment que tem um token compartilhado de reserva (o serviço hospedado eastagiletracker.com tem um; uma instalação self-hosted não tem nenhum até que seu operador defina GITHUB_IMPORT_PAT), e nunca com o --engine direct do GitHub-to-EAT. Veja Tokens e limites de taxa.
• Node.js 22+ — só para o caminho do GitHub-to-EAT no passo 3. O caminho pela API não precisa de nada além de curl.

1. Criar o projeto

O projeto tem de existir antes da chave de agente, e tem de ser criado por uma pessoa: chaves de agente ficam presas a um projeto no momento da emissão e não conseguem criar projetos. Crie-o na interface, ou com a sua própria chave ea_user_…:

curl -X POST https://eastagiletracker.com/api/v1/projects \
  -H "X-TrackerToken: $TRACKER_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "hello-world", "iteration_length_weeks": 1}'

A resposta carrega o project_id de que toda chamada abaixo precisa.

2. Emitir uma chave de agente

Um proprietário do projeto cria chaves de agente em Configurações do projeto → Agentes. O papel que você escolher decide quanto desta página o agente consegue fazer sozinho, e há duas respostas sensatas:

• owner — uma única chave roda o ciclo inteiro, importação incluída. Importar é exclusivo do proprietário, porque uma importação reescreve o formato do projeto por inteiro. Emitir um agente com papel owner exige que você mesmo seja proprietário do projeto: o papel de um agente nunca pode ultrapassar o de quem o criou.
• member — privilégio mínimo. O agente assume histórias, move-as, comenta e vincula pull requests, mas não consegue importar. A importação você mesmo executa (passo 5) com a sua chave, e depois entrega o quadro ao agente.

De um jeito ou de outro, não deixe no padrão. Uma chave de agente nova é viewer enquanto você não disser outra coisa, e um viewer lê o quadro mas não assume nem move uma história — que é quase todo este ciclo.

Chaves de agente importam aqui por uma razão que vai além do acesso. Uma chave de agente age como participante nomeado em um único projeto, então cada história que ela cria, cada mudança de estado que faz e cada comentário que escreve fica atribuído a esse agente no histórico — distinguível do seu próprio trabalho em vez de misturado a ele.

export TRACKER_TOKEN="ea_agent_xxxxx"

Faça o agente ler /meta antes de qualquer coisa:

curl https://eastagiletracker.com/api/v1/meta \
  -H "X-TrackerToken: $TRACKER_TOKEN"

Isso responde às duas perguntas que o agente teria de adivinhar: a qual projeto a chave está presa (auth.project_id) e quais mudanças de estado são legais para cada tipo de história (transitions). Uma feature percorre unstarted → started → finished → delivered → accepted; uma chore é só unstarted → started → accepted. Ler o mapa vence codificá-lo à mão.

3. Importar com o GitHub-to-EAT

O GitHub-to-EAT é o importador de código aberto da própria East Agile: uma ferramenta de linha de comando licenciada sob MIT que faz todo o passo de povoamento — os passos 4 e 5 abaixo — em um comando. Recorra a ela quando há uma pessoa diante de um terminal. Recorra à API embaixo dela quando é um agente que conduz sem supervisão e quer o identificador do job para consultar.

Ela precisa de Node.js 22+ e não tem dependências de execução próprias. Ainda não está publicada no npm, então instale-a a partir do repositório:

git clone git@github.com:EastAgile/GitHub-to-EAT.git
cd GitHub-to-EAT
npm install --global .

Depois aponte-a para a chave emitida no passo 2 e o projeto criado no passo 1:

export EAT_AGENT_KEY="ea_agent_xxxxx"
github-to-eat --project $PROJECT_ID --repo octocat/hello-world

Ela imprime primeiro uma legenda do mapeamento — exatamente como cada tipo selecionado vai aterrissar — e pede confirmação antes de escrever qualquer coisa. Fora de um terminal, num pipe, em CI ou dentro de um agente, não há onde mostrar essa pergunta, então uma execução que fosse escrever tem de passar --yes; sem isso a ferramenta sai com 2 e não escreve nada, em vez de adivinhar a sua resposta. Rodar de novo é seguro: o que já foi importado é ignorado, nunca duplicado.

Flag	O que faz
--dry-run	Verificação prévia e depois imprime o plano que executaria — quantas histórias importaria, quantas ignoraria por já estarem lá — sem escrever nada. Não precisa de --yes.
--include	Quais tipos importar, separados por vírgula: issues,prs,milestones,releases,deps. O padrão é issues, e toda seleção precisa contê-lo. São os mesmos opt-ins da tabela do passo 6.
--token	Seu token de acesso pessoal do GitHub (GITHUB_TOKEN no ambiente ou num .env também vale). Ele precisa de repo, ou da permissão granular Issues: Read, naquele repositório. Obrigatório para um repositório privado, para um servidor sem token compartilhado de reserva e sempre para --engine direct. Omita-o no motor padrão do serviço hospedado e o Tracker gasta o próprio orçamento compartilhado — veja Tokens e limites de taxa.
--engine	server, o padrão, envia uma chamada /import/json e deixa o Tracker buscar, mapear e escrever. direct roda esse mesmo pipeline na sua máquina e escreve pela API pública — ou seja, lê o GitHub por conta própria e sempre precisa de um token, saindo com 2 sem ele.
--states, --milestones, --story-type, --no-comments, --no-tasks	Restringem ou sobrescrevem o mapeamento para uma execução; nada é persistido. Cada um implica --engine direct.

Defina EAT_API_BASE e EAT_APP_BASE para apontá-la a um Tracker auto-hospedado ou local; ambos apontam por padrão ao serviço hospedado. O README traz a referência completa das flags, os códigos de saída e a solução de problemas.

Tudo abaixo é essa mesma importação conduzida chamada a chamada, que é o que você quer quando é um agente que a executa.

4. Primeiro uma execução a seco

Importar é exclusivo do proprietário — use uma chave de agente com papel owner, ou a sua própria chave se deixou o agente em member. Rode primeiro com dry_run, antes de deixá-la escrever:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/import/json \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "source": "github",
        "owner": "octocat",
        "repo": "hello-world",
        "include_pull_requests": true,
        "include_milestones": true,
        "dry_run": true
      }'

Uma execução a seco busca do GitHub, resolve e remove duplicatas exatamente como a de verdade, relata as mesmas contagens — imported, skipped, errors, unmatched — e depois reverte a transação inteira. Nada persiste e nenhum evento de importação concluída chega ao seu log de auditoria. É o jeito mais barato de descobrir que você queria incluir os milestones, ou que um repo é maior do que pensava, enquanto isso ainda não custa nada.

Toda chamada a /import/json é assíncrona, inclusive a execução a seco: o endpoint devolve 202 com um identificador de job, não um resultado, e as contagens chegam no job quando você o consulta (passo 5). O job de uma execução a seco chega a done como o de uma execução real; a diferença é que nada foi gravado.

5. Rodar a importação

Tire o dry_run e envie de novo. Como antes, o endpoint devolve 202 com um identificador de job:

{ "import_id": "…", "status": "pending" }

Consulte o job até ele chegar a um estado terminal:

curl https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/imports/$IMPORT_ID \
  -H "X-TrackerToken: $TRACKER_TOKEN"

O status percorre pending → fetching → writing → done | failed. Só os dois últimos são terminais: done carrega as contagens do resultado, failed carrega uma mensagem de erro e um código de máquina estável em que você pode ramificar. Enquanto a busca pagina, progress_current e progress_total dizem em qual página ela está — vale exibir se há uma pessoa acompanhando.

Tokens. Passe "token": "github_pat_…". Omita e o servidor substitui pelo token de plataforma compartilhado, que só lê repositórios públicos e é debitado de todos os chamadores do deployment — Tokens e limites de taxa cobre o que isso custa a você. Seja qual for o token usado, ele conduz as chamadas ao GitHub e nada mais: nunca vai para o log, nunca para o log de auditoria, nunca é armazenado e nunca é devolvido numa resposta ou num erro.

Rodar de novo é seguro. Uma linha já importada é reconhecida pelo id de origem e ignorada, não duplicada. Uma segunda importação completa o quadro com o que apareceu desde a primeira.

6. O que aterrissa no quadro

As issues são importadas por padrão. Todo o resto é opt-in, uma flag por tipo:

Do GitHub	Vira	Flag
Issue	Uma história. Aberta → unstarted no Backlog. Fechada → accepted, ou rejected quando o GitHub diz que a issue foi fechada como not_planned ou duplicate (a história leva então uma etiqueta correspondente).	padrão
Checklist no corpo da issue	Tarefas — cada linha - [ ] / - [x] vira uma tarefa na ordem do corpo, e [x] chega já concluída. A checklist também permanece na descrição.	padrão
Etiquetas	Etiquetas, trazidas como estão.	padrão
Pull request	Uma história com a etiqueta pull-request. Aberto → started, mesclado → accepted, fechado sem mesclar → rejected.	include_pull_requests
Milestone	Um épico, intitulado a partir do milestone e deduplicado por título — duas issues que dividem um milestone caem em um só épico. Com a flag desligada ele vem junto como etiqueta milestone:<título>.	include_milestones
Release	Uma história de release. Publicada → accepted, rascunho → unstarted.	include_releases
Dependência de issue	Um bloqueador na história. Só issues, nunca pull requests.	include_dependencies

O tipo de história é inferido quando a issue não diz. Uma etiqueta contendo bug, fix ou defect — ou um título começando por fix ou bug — faz dela um bug; chore, maintenance, devops ou infra fazem dela uma chore; qualquer outra coisa é uma feature. Vale saber antes de importar, porque no East Agile Tracker só as features carregam pontos e só as features alimentam a velocidade. Veja Introdução → Histórias.

7. O agente trabalha uma história

Agora o quadro tem histórico e o agente tem uma chave. Daqui em diante o ciclo são quatro chamadas.

Achar uma história, ou escrever uma. Filtre o quadro atrás de algo para assumir:

curl "https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories?state=unstarted" \
  -H "X-TrackerToken: $TRACKER_TOKEN"

import_source=github restringe ao que a importação trouxe. Se o agente encontrou trabalho que o repo nunca registrou, ele cria a história em vez disso — veja Guia da API → Criar uma história.

Assumi-la. Um agente se adiciona como proprietário enviando um corpo vazio:

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/owners \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Um corpo vazio significa quem chama, então o agente não precisa saber o próprio id. O quadro agora mostra o agente como proprietário, que é como uma pessoa que acompanha sabe que o trabalho está tomado.

Iniciá-la.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/transitions \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "started"}'

Depois o agente vai e faz o trabalho — lê o repo, escreve o código, abre o pull request. Essa parte acontece na sua ferramenta de desenvolvimento, não aqui.

Anexar o pull request.

curl -X POST https://eastagiletracker.com/api/v1/projects/$PROJECT_ID/stories/$STORY_ID/links \
  -H "X-TrackerToken: $TRACKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/octocat/hello-world/pull/42"}'

Uma URL de pull request do GitHub é reconhecida como tal — você não precisa dizer. A história e o código que a fecha ficam a um clique um do outro, nos dois sentidos.

Concluí-la. Passe para finished e pare aí. Uma feature ainda tem delivered e accepted pela frente, e esses são os portões de revisão: alguém que não o agente decide que o trabalho está certo. Uma chore não tem esse portão — started → accepted é todo o caminho que lhe resta.

Tokens e limites de taxa

Toda importação se autentica. A busca de issues, comentários e pull requests corre na API GraphQL do GitHub, e o GraphQL recusa uma requisição sem token — não há camada anônima, nem num repositório público nem num privado. A pergunta nunca é se um token vai ao GitHub, apenas de quem.

O seu próprio token

Passe token na chamada de importação, ou --token ao GitHub-to-EAT. Um token de acesso pessoal granular com leitura das issues do repositório basta. Ele conduz as chamadas ao GitHub e nada mais: nunca vai para o log, nunca para o log de auditoria, nunca é armazenado e nunca é devolvido numa resposta ou num erro.

Traga o seu para qualquer coisa além de uma demonstração. Assim você gasta um orçamento que mais ninguém toca, e nenhuma verificação prévia pode recusá-lo por causa da importação de outra pessoa.

--engine direct não lhe deixa escolha. Esse motor lê o GitHub a partir da sua máquina em vez de pelo Tracker, então o token do servidor fica fora de alcance; uma execução sem token sai com 2 e um erro de uso antes de buscar ou escrever qualquer coisa. GITHUB_TOKEN no seu ambiente ou no seu .env vale o mesmo que --token.

O que obriga ao token é o percurso das issues, não o motor inteiro. O direct lê issues, comentários e pull requests por GraphQL, que não tem modo anônimo; ele toca REST apenas para a listagem de releases e para a sondagem gratuita /rate_limit. A ferramenta ainda traz um leitor REST anônimo mais antigo que levava uma importação de repositório público dentro do orçamento de 60 por hora, mas nenhum caminho da CLI o alcança mais e ele está previsto para remoção — portanto trate --token como obrigatório para o direct.

O token compartilhado do deployment

Não envie token algum e o servidor substitui pelo token de plataforma que o operador configurou (GITHUB_IMPORT_PAT). Três limites vêm junto:

• É configuração opcional. O serviço hospedado eastagiletracker.com provisiona um, então uma importação de repositório público sem token funciona lá. Uma instalação self-hosted — o binário baixado — não tem nenhum até que seu operador defina GITHUB_IMPORT_PAT no ambiente, e até lá recusa toda importação sem token com 400 import_github_no_token.
• Ele lê apenas repositórios públicos. O serviço hospedado o emite somente-leitura sobre repos públicos, então um repositório privado sempre exige o seu próprio token.
• Todos os chamadores do deployment dividem um orçamento. Antes de uma importação sem token rodar, o servidor lê os pontos GraphQL restantes do token compartilhado e a recusa com 400 import_github_shared_quota_low abaixo de 500. Um orçamento que acaba no meio da importação faz o job falhar com import_github_rate_limited_platform. As duas mensagens apontam a mesma correção: fornecer o seu próprio token.

O que o token compra

O GitHub mede suas duas APIs separadamente, e o teto sem autenticação é duas ordens de grandeza menor.

API do GitHub	Usada para	Com token	Sem token
GraphQL	Issues, comentários, pull requests, sub-issues, dependências	5.000 pontos por hora, pontuados sobre os nós que a consulta devolve	Recusado — o GraphQL não tem camada anônima
REST	Releases (include_releases) e a verificação prévia /rate_limit	5.000 requisições por hora	60 requisições por hora, contadas por endereço IP e divididas com todos que estão atrás dele

Uma importação nunca cai para essa faixa de 60 por hora: sem token para enviar, a requisição é recusada de saída em vez de repetida anonimamente. O número importa pelo que você faz em volta da importação — um script que lê o GitHub direto, ou um shell na mesma rede que outros clientes, esgota 60 requisições em segundos.

Leia o seu orçamento restante quando quiser; GET /rate_limit está isento dos dois limites, então a conferência não custa nada:

curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/rate_limit

Pontos GraphQL não são requisições. O GitHub pontua uma consulta pelos nós que ela devolve, então uma página de 100 issues com seus comentários e responsáveis custa muitos pontos, e um repositório grande gasta o orçamento horário em bem menos chamadas do que os números da era REST sugerem. --dry-run (passo 3) e dry_run (passo 4) custam cada um os mesmos pontos que a busca real — é isso que torna as suas contagens confiáveis — então conte com duas passagens quando preparar uma importação grande.

Para onde ir agora

• Guia da API — a gramática de busca, o fluxo de eventos, as transições em lote, as escritas idempotentes e o resto da superfície.
• Instruções de operação — as mesmas operações pela interface, e os outros dez importadores.
• Introdução — por que a máquina de estados e os quatro tipos de história têm esse formato.
• GitHub-to-EAT — o repositório do importador: cada flag, os dois motores, e como contribuir.