Punuin ang isang proyekto mula sa isang GitHub repo

Ituro ang isang agent sa isang GitHub repository at makukuha mo pabalik ang isang gumaganang board: bawat issue ay isang story, nasa estadong sinasabi ng kasaysayan nito, kasama ang mga checklist, label, at milestone na dala-dala. Pagkatapos ay pupulutin ng parehong agent ang isang story, aangkinin ito, igagalaw ito sa state machine, at ikakabit ang pull request na binuksan nito.

Ang pahinang ito ang buong loop na iyon mula dulo hanggang dulo. May dalawang ruta ang hakbang ng pagpupuno: ang GitHub-to-EAT, ang open-source na importer ng East Agile, ay ginagawa ito sa isang utos (hakbang 3); ang import API ay ginagawa ang parehong trabaho bawat tawag (mga hakbang 4 at 5), at iyon ang pinapatakbo ng isang agent kapag gusto nito ang hawakan ng trabaho. Lahat ng kasunod ay tumatakbo sa API, dahil ang punto ay kayang tapusin ng isang agent ang natitira nang walang bantay.

Hindi ito isang hiwalay na «AI import». Ang hakbang ng pagpupuno ay ang parehong GitHub importer na kaya mong patakbuhin nang manu-mano mula sa Mga setting ng proyekto → Import / Export, inilalarawan sa Mga tagubilin sa pagpapatakbo → Pag-import mula sa ibang tracker. Tinatawag ng agent ang parehong endpoint na tatawagin mo. Ang idinadagdag ng pahinang ito ay ang lahat ng nakapaligid dito: sino ang may hawak ng susi, paano suriin ang import bago ito magsulat, at ano ang ginagawa ng agent sa board kapag mayroon na nito.

Ang GitHub source sa tab na Import / Export: may laman ang owner at repository, blangko ang token, naka-tsek ang pull requests at milestones

Ano ang kailangan mo

Isang proyekto — at isang session o isang ea_user_… key na pang-gawa nito.
Isang agent key — isang ea_agent_… key na nakatakda sa proyektong iyon. Ang rolyong kailangan nito ay depende sa gaano karami sa loop ang gusto mong patakbuhin ng agent; tingnan ang hakbang 2. Tingnan din ang Gabay sa API → Dalawang uri ng key.
Isang GitHub personal access token — na may pahintulot magbasa ng mga issue ng repository. Bawat import ay nagpapatotoo, dahil tumatakbo ang pagkuha sa GraphQL API ng GitHub at tinatanggihan ng GraphQL ang isang kahilingang walang token. Maaari mo lamang itong iwan kapag ang Tracker ang kumukuha para sa iyo: isang pampublikong repository, sa isang deployment na may shared na fallback token (may isa ang naka-host na eastagiletracker.com; walang anuman ang self-hosted na instalasyon hangga’t hindi itinatakda ng operator nito ang GITHUB_IMPORT_PAT), at hindi sa --engine direct ng GitHub-to-EAT. Tingnan ang Mga token at rate limit.
Node.js 22+ — para lamang sa rutang GitHub-to-EAT sa hakbang 3. Ang rutang API ay walang kailangan kundi curl.

1. Gawin ang proyekto

Kailangang umiral ang proyekto bago ang agent key, at kailangang isang tao ang gumawa nito: ang mga agent key ay nakatali sa isang proyekto sa oras ng paglikha at hindi makakalikha ng proyekto. Gawin ito sa interface, o gamit ang sarili mong ea_user_… key:

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}'

Dala ng tugon ang project_id na kailangan ng bawat tawag sa ibaba.

2. Lumikha ng isang agent key

Ang may-ari ng proyekto ay gumagawa ng mga agent key sa Mga setting ng proyekto → Mga agent. Ang rolyong pipiliin mo ang magpapasya kung gaano karami sa pahinang ito ang kayang gawin ng agent nang mag-isa, at may dalawang makatuwirang sagot:

owner — isang key ang tumatakbo sa buong loop, pati na ang import. Ang pag-import ay para lamang sa may-ari, dahil binabago ng isang import ang buong hugis ng isang proyekto nang sabay-sabay. Ang paglikha ng agent na may rolyong owner ay nangangailangang ikaw mismo ay may-ari ng proyekto: ang rolyo ng isang agent ay hindi kailanman hihigit sa rolyo ng lumikha nito.
member — pinakamababang pribilehiyo. Ang agent ay umaangkin ng mga story, iginagalaw ang mga ito, nagkokomento, at nag-uugnay ng mga pull request, ngunit hindi makapag-import. Ikaw mismo ang magpapatakbo ng import (hakbang 5) gamit ang sarili mong key, saka mo ibibigay ang board sa agent.

Alinman ang piliin, huwag itong iwan sa default. Ang isang bagong agent key ay viewer hangga’t wala kang sinasabing iba, at ang isang viewer ay nakakabasa ng board ngunit hindi nakakaangkin o nakakagalaw ng story — at iyon ang halos buong loop na ito.

Mahalaga ang mga agent key dito sa dahilang lampas sa pag-access. Ang isang agent key ay kumikilos bilang pinangalanang kalahok sa iisang proyekto, kaya ang bawat story na nililikha nito, ang bawat pagbabago ng estado na ginagawa nito, at ang bawat komentong isinusulat nito ay iniuugnay sa agent na iyon sa kasaysayan — nakikilalang hiwalay sa sarili mong trabaho sa halip na nahalo rito.

export TRACKER_TOKEN="ea_agent_xxxxx"

Pabasahin sa agent ang /meta bago ang lahat:

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

Sinasagot nito ang dalawang tanong na huhulaan lamang sana ng agent: kung aling proyekto ang kinatalian ng key (auth.project_id), at kung aling mga paggalaw ng estado ang legal para sa bawat uri ng story (transitions). Ang isang feature ay dumadaan sa unstarted → started → finished → delivered → accepted; ang isang chore ay unstarted → started → accepted lamang. Mas mainam basahin ang mapa kaysa i-hard-code ito.

3. Mag-import gamit ang GitHub-to-EAT

Ang GitHub-to-EAT ay ang sariling open-source na importer ng East Agile: isang kasangkapan sa command line na lisensyado sa ilalim ng MIT na ginagawa ang buong hakbang ng pagpupuno — ang mga hakbang 4 at 5 sa ibaba — sa isang utos. Gamitin ito kapag may taong nasa harap ng terminal. Gamitin ang API sa ilalim nito kapag isang agent ang nagpapatakbo nang walang bantay at gusto ang hawakan ng trabaho para subaybayan.

Kailangan nito ang Node.js 22+ at walang sariling runtime dependency. Hindi pa ito nailalathala sa npm, kaya i-install ito mula sa repository:

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

Pagkatapos ay ituro ito sa key na ginawa mo sa hakbang 2 at sa proyektong ginawa mo sa hakbang 1:

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

Nagpi-print muna ito ng alituntunin ng pagtutugma — kung paano eksaktong daratal ang bawat piniling uri — at humihingi ng kumpirmasyon bago ito magsulat ng kahit ano. Sa labas ng terminal, sa isang pipe, sa CI o sa isang agent, walang mapagpapakitaan ng prompt na iyon, kaya ang isang takbong magsusulat ay kailangang magpasa ng --yes; kung wala nito, lumalabas ang kasangkapan nang 2 at walang isinusulat sa halip na hulaan ang sagot mo. Ligtas ang muling pagpapatakbo: ang na-import na ay nilalaktawan, hindi kailanman dinodoble.

Flag	Ano ang ginagawa
`--dry-run`	Paunang pagsusuri, tapos i-print ang planong isasagawa sana nito — ilang story ang ii-import, ilan ang laktawan dahil naroon na — at walang isinusulat. Hindi nangangailangan ng `--yes`.
`--include`	Aling mga uri ang ii-import, pinaghihiwalay ng kuwit: `issues,prs,milestones,releases,deps`. Ang default ay `issues`, at kailangang taglayin ito ng bawat pinili. Ito ang parehong mga opsyon gaya ng talahanayan sa hakbang 6.
`--token`	Ang iyong GitHub personal access token (bilang din ang `GITHUB_TOKEN` sa environment o sa isang `.env`). Kailangan nito ang `repo`, o ang pinong Issues: Read, sa repository na iyon. Kailangan para sa isang pribadong repository, para sa isang server na walang shared na fallback token, at palaging para sa `--engine direct`. Iwan ito sa default na engine ng hosted na serbisyo at gagamitin ng Tracker ang sarili nitong shared na badyet — tingnan ang Mga token at rate limit.
`--engine`	Ang `server`, ang default, ay nagpapadala ng isang tawag na `/import/json` at hinahayaan ang Tracker na kumuha, magtugma at magsulat. Ang `direct` ay pinapatakbo ang parehong pipeline sa makina mo at nagsusulat sa pamamagitan ng pampublikong API — kaya siya mismo ang nagbabasa ng GitHub at laging kailangan ng token, lumalabas nang `2` kung wala.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Pinaliliit o pinapalitan ang pagtutugma para sa isang takbo; walang nananatili. Bawat isa sa kanila ay may kasamang `--engine direct`.

Itakda ang EAT_API_BASE at EAT_APP_BASE para ituro ito sa isang self-hosted o lokal na Tracker; pareho silang nakaturo bilang default sa hosted na serbisyo. Ang README ang may buong sanggunian ng mga flag, ang mga exit code, at ang pag-troubleshoot.

Lahat ng nasa ibaba ay ang parehong import na pinapatakbo bawat tawag, at iyon ang gusto mo kapag isang agent ang nagpapatakbo nito.

4. Dry run muna

Ang pag-import ay para lamang sa may-ari — gumamit ng agent key na may rolyong owner, o ang sarili mong key kung iniwan mo ang agent sa member. Patakbuhin muna ito nang may dry_run, bago mo ito hayaang magsulat ng kahit ano:

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
      }'

Ang isang dry run ay kumukuha mula sa GitHub, nireresolba, at ide-de-dupe nang eksakto gaya ng totoo, iniuulat ang parehong mga bilang — imported, skipped, errors, unmatched — at pagkatapos ay ibinabalik ang buong transaksyon. Walang nananatili at walang kaganapang natapos na import ang umaabot sa iyong audit log. Ito ang pinakamurang paraan para malaman na ang ibig mo palang sabihin ay isama ang mga milestone, o na mas malaki ang isang repo kaysa sa akala mo, habang wala pa itong halagang binabayaran.

Asinkrono ang bawat tawag sa /import/json, pati na ang dry run: nagbabalik ang endpoint ng 202 kasama ang isang hawakan ng trabaho, hindi ng resulta, at dumarating ang mga bilang sa trabaho kapag sinuri mo ito (hakbang 5). Umaabot sa done ang trabaho ng isang dry run gaya ng sa totoo; ang pagkakaiba ay walang naisulat.

5. Patakbuhin ang import

Alisin ang dry_run at ipadala itong muli. Gaya ng dati, ang endpoint ay nagbabalik ng 202 kasama ang isang hawakan ng trabaho:

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

Suriin ang trabaho hanggang maabot nito ang isang huling estado:

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

Ang katayuan ay dumadaan sa pending → fetching → writing → done | failed. Dalawa lang ang huli sa mga ito: dala ng done ang mga bilang ng resulta, dala ng failed ang mensahe ng error at isang matatag na machine code na masasanga mo. Habang nagpapahina-hina ang pagkuha, sinasabi ng progress_current at progress_total kung nasaang pahina ito — sulit ipakita kung may taong nanonood.

Mga token. Ipasa ang "token": "github_pat_…". Iwan ito at papalitan ng server ng shared na platform token, na pampublikong repository lang ang nababasa at ibinabawas sa bawat tumatawag sa deployment — sinasaklaw ng Mga token at rate limit kung ano ang halaga niyon sa iyo. Anuman ang token na ginamit, pinapatakbo nito ang mga upstream na tawag sa GitHub at wala nang iba: hindi ito kailanman nilo-log, hindi kailanman ini-audit-log, hindi kailanman iniimbak, at hindi kailanman ina-echo pabalik sa isang tugon o isang error.

Ligtas ang muling pagpapatakbo. Ang isang hilerang na-import na ay tinutugma sa pamamagitan ng source id nito at nilalaktawan, hindi dinodoble. Ang pangalawang import ay pinupunuan ang board ng anumang lumitaw simula noong una.

6. Ano ang dumadaong sa board

Ang mga issue ay ini-import bilang default. Lahat ng iba ay opt-in, isang flag bawat uri:

Mula sa GitHub	Nagiging	Flag
Issue	Isang story. Bukas → unstarted sa Backlog. Sarado → accepted, o rejected kapag sinasabi ng GitHub na ang issue ay isinara bilang `not_planned` o `duplicate` (may kaakibat na label ang story).	default
Checklist sa katawan ng issue	Mga task — bawat linyang `- [ ]` / `- [x]` ay nagiging isang task ayon sa pagkakasunod sa katawan, at dumarating ang `[x]` na tapos na. Nananatili rin ang checklist sa paglalarawan.	default
Mga label	Mga label, dinadala nang buo.	default
Pull request	Isang story na may label na `pull-request`. Bukas → started, na-merge → accepted, sarado nang hindi na-merge → rejected.	`include_pull_requests`
Milestone	Isang epic, pinangalanan ayon sa milestone, dine-dedupe ayon sa pamagat — dalawang issue na may parehong milestone ay dumadaong sa isang epic. Kapag naka-off ang flag, sumasama ito bilang label na `milestone:<pamagat>`.	`include_milestones`
Release	Isang release story. Nailathala → accepted, draft → unstarted.	`include_releases`
Dependency ng issue	Isang blocker sa story. Mga issue lamang, hindi kailanman pull request.	`include_dependencies`

Hinihinuha ang uri ng story kapag hindi ito sinasabi ng issue. Ang isang label na naglalaman ng bug, fix, o defect — o isang pamagat na nagsisimula sa fix o bug — ay ginagawa itong bug; ang chore, maintenance, devops, o infra ay ginagawa itong chore; ang iba pa ay feature. Sulit itong malaman bago mag-import, dahil sa East Agile Tracker ang mga feature lamang ang may point at ang mga feature lamang ang nagpapakain sa velocity. Tingnan ang Panimula → Mga story.

Isang project board kaagad matapos i-import ang sample repository: mga issue bilang story kasama ang kanilang label, milestones bilang epic at mga tao sa GitHub bilang owner

7. Pinagtatrabahuhan ng agent ang isang story

Ngayon ay may kasaysayan na ang board, at may susi na ang agent. Apat na tawag na lamang ang loop mula rito.

Maghanap ng story, o magsulat ng isa. Salain ang board para sa isang bagay na mapupulot:

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

Ang import_source=github ay nililimitahan ito sa dinala ng import. Kung nakatagpo ang agent ng trabahong hindi kailanman naitala ng repo, gumagawa ito ng story sa halip — tingnan ang Gabay sa API → Gumawa ng story.

Angkinin ito. Idinaragdag ng isang agent ang sarili bilang may-ari sa pamamagitan ng pag-POST ng walang lamang body:

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 '{}'

Ang walang lamang body ay nangangahulugang ang tumatawag, kaya hindi kailangang malaman ng agent ang sarili nitong id. Ipinapakita na ngayon ng board ang agent bilang may-ari, at doon nalalaman ng taong nanonood na may kumuha na ng trabaho.

Simulan ito.

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"}'

Pagkatapos ay pupunta ang agent at gagawin ang trabaho — babasahin ang repo, isusulat ang code, bubuksan ang pull request. Nangyayari ang bahaging iyon sa iyong coding tool, hindi rito.

Ikabit ang 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"}'

Ang isang GitHub pull-request URL ay nakikilala bilang ganoon — hindi mo na kailangang sabihin. Ang story at ang code na nagsasara nito ay isang klik na lamang ang layo sa isa’t isa, sa magkabilang direksyon.

Tapusin ito. Ilipat sa finished at huminto roon. May delivered at accepted pa sa unahan ng isang feature, at iyon ang mga tarangkahan ng pagsusuri: may ibang tao, hindi ang agent, ang nagpapasyang tama ang trabaho. Walang ganoong tarangkahan ang isang chore — ang started → accepted ang buong natitira nitong daan.

Isang na-import na saradong issue na ang seksiyong CODE ay naka-link sa pull request na nag-ayos dito, katabi ng mga komento mula sa GitHub

Mga token at rate limit

Bawat import ay nagpapatotoo. Ang pagkuha ng issue, komento, at pull request ay tumatakbo sa GraphQL API ng GitHub, at tinatanggihan ng GraphQL ang isang kahilingang walang token — walang anonymous na antas, sa pampubliko man na repository o sa pribado. Ang tanong ay hindi kailanman kung may token na napupunta sa GitHub, kundi kaninong token lamang.

Ang sarili mong token

Ipasa ang token sa tawag ng import, o --token sa GitHub-to-EAT. Sapat na ang isang pinong personal access token na may pahintulot magbasa ng mga issue ng repository. Pinapatakbo nito ang mga upstream na tawag sa GitHub at wala nang iba: hindi ito kailanman nilo-log, hindi kailanman ini-audit-log, hindi kailanman iniimbak, at hindi kailanman ina-echo pabalik sa isang tugon o isang error.

Magdala ng sarili mo para sa anumang lampas sa isang demo. Gumagastos ka noon mula sa badyet na walang ibang gumagalaw, at walang paunang pagsusuri ang makakatanggi sa iyo dahil sa import ng iba.

Walang pagpipilian sa --engine direct. Binabasa ng engine na iyon ang GitHub mula sa makina mo sa halip na sa pamamagitan ng Tracker, kaya wala nang maabot na token ng server; ang isang takbong walang token ay lumalabas nang 2 na may usage error bago pa ito kumuha o magsulat ng kahit ano. Bilang ang GITHUB_TOKEN sa environment mo o sa .env mo, gaya rin ng --token.

Ang paglakad sa mga issue ang nag-oobliga ng token, hindi ang buong engine. Binabasa ng direct ang mga issue, komento at pull request sa GraphQL, na walang anonymous na mode; hinahawakan nito ang REST para lamang sa listahan ng releases at sa libreng /rate_limit na pagsusuri. Naghahatid pa rin ang tool ng mas lumang anonymous na REST fetcher na nagpapatakbo ng import ng pampublikong repository sa loob ng badyet na 60 kada oras, ngunit wala nang landas sa CLI ang umaabot dito at nakatakda itong burahin, kaya ituring na kailangan ang --token para sa direct.

Ang shared na token ng deployment

Huwag magpadala ng token at papalitan ng server ng platform token na na-configure ng operator nito (GITHUB_IMPORT_PAT). May tatlong hangganang kasama nito:

Opsyonal na configuration ito. Nagbibigay ang naka-host na eastagiletracker.com ng isa, kaya gumagana roon ang import ng pampublikong repository na walang token. Ang self-hosted na instalasyon — ang na-download na binary — ay wala nito hangga’t hindi itinatakda ng operator nito ang GITHUB_IMPORT_PAT sa environment, at hanggang doon ay tinatanggihan nito ang bawat import na walang token gamit ang 400 import_github_no_token.
Pampublikong repository lang ang nababasa nito. Nililikha ito ng hosted na serbisyo bilang read-only sa mga pampublikong repo, kaya laging kailangan ng pribadong repository ang sarili mong token.
Bawat tumatawag sa deployment ay may iisang badyet. Bago tumakbo ang isang import na walang token, binabasa ng server ang natitirang GraphQL points ng shared na token at tinatanggihan ito ng 400 import_github_shared_quota_low kapag mas mababa sa 500. Ang badyet na naubos sa gitna ng import ay nagpapabagsak sa trabaho gamit ang import_github_rate_limited_platform. Pareho ang inihahain ng dalawang mensahe: magbigay ng sarili mong token.

Ano ang binibili ng token

Hiwalay na sinusukat ng GitHub ang dalawang API nito, at ang hangganang walang patotoo ay dalawang orden ng magnitud na mas mababa.

GitHub API	Ginagamit para sa	May token	Walang token
GraphQL	Mga issue, komento, pull request, sub-issue, dependency	5,000 puntos kada oras, iskor batay sa mga node na ibinabalik ng isang query	Tinanggihan — walang anonymous na antas ang GraphQL
REST	Mga release (`include_releases`), at ang paunang `/rate_limit`	5,000 kahilingan kada oras	60 kahilingan kada oras, binibilang kada IP address at hinahati sa lahat ng nasa likod nito

Hindi kailanman bumabagsak ang isang import sa antas na 60 kada oras: dahil walang token na maipapadala, tinatanggihan agad ang kahilingan sa halip na subukan itong muli nang anonymous. Mahalaga ang bilang na iyon para sa ginagawa mo sa paligid ng import — isang script na direktang nagbabasa ng GitHub, o isang shell sa parehong network ng ibang kliyente, ay nauubos ang 60 kahilingan sa ilang segundo.

Basahin ang natitirang badyet mo anumang oras; hindi saklaw ng dalawang limitasyon ang GET /rate_limit, kaya walang bayad ang pagsusuri:

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

Ang GraphQL points ay hindi mga kahilingan. Iniiskor ng GitHub ang isang query batay sa mga node na ibinabalik nito, kaya ang isang pahina ng 100 issue kasama ang kanilang mga komento at assignee ay nagkakahalaga ng maraming puntos, at nauubos ng isang malaking repository ang oras-oras na badyet sa mas kaunting tawag kaysa sa ipinahihiwatig ng mga bilang noong panahon ng REST. Ang --dry-run (hakbang 3) at ang dry_run (hakbang 4) ay parehong nagkakahalaga ng ganoon ding puntos gaya ng totoong pagkuha — iyon ang nagpapatiwala sa mga bilang nila — kaya maglaan ng dalawang pasada kapag paunang sinusuri mo ang isang malaking import.

Saan susunod

Gabay sa API — ang gramatika ng paghahanap, ang daloy ng kaganapan, ang mga bulk transition, ang mga idempotent na pagsulat, at ang natitirang bahagi ng ibabaw.
Mga tagubilin sa pagpapatakbo — ang parehong mga operasyon mula sa interface, at ang sampung iba pang importer.
Panimula — kung bakit ganito ang hugis ng state machine at ng apat na uri ng story.
GitHub-to-EAT — ang sariling repository ng importer: bawat flag, ang dalawang engine, at kung paano mag-ambag dito.