Täytä projekti GitHub-repositoriosta

Osoita agentti GitHub-repositorioon, niin saat takaisin toimivan taulun: jokainen issue storyna, siinä tilassa jonka sen historia sanelee, tarkistuslistat, tunnisteet ja virstanpylväät mukanaan. Sitten sama agentti poimii storyn, ottaa sen itselleen, vie sen tilakoneen läpi ja liittää avaamansa pull requestin.

Tämä sivu käy sen silmukan läpi alusta loppuun. Täyttövaiheella on kaksi reittiä: GitHub-to-EAT, East Agilen avoimen lähdekoodin tuontityökalu, hoitaa sen yhdellä komennolla (vaihe 3); tuonti-API tekee saman työn kutsu kerrallaan (vaiheet 4 ja 5), ja juuri sitä agentti ohjaa, kun se haluaa työn kahvan. Kaikki sen jälkeen kulkee API:n kautta, koska koko pointti on, että agentti selviää lopusta ilman valvontaa.

Tämä ei ole erillinen ”tekoälytuonti”. Täyttövaihe on sama GitHub-tuonti, jonka voit ajaa käsin kohdasta Projektin asetukset → Tuo / Vie, kuvattuna sivulla Käyttöohjeet → Tuonti muista trackereista. Agentti kutsuu samaa päätepistettä kuin sinä. Tämä sivu lisää kaiken sen ympäriltä: kuka pitää avainta, miten tuonti tarkistetaan ennen kuin se kirjoittaa, ja mitä agentti tekee taululla sen jälkeen kun se on olemassa.

Mitä tarvitset

• Projektin — ja istunnon tai ea_user_…-avaimen, jolla luot sen.
• Agenttiavaimen — kyseiseen projektiin rajatun ea_agent_…-avaimen. Tarvittava rooli riippuu siitä, kuinka suuren osan silmukasta haluat agentin ajavan; katso vaihe 2. Katso myös API-opas → Kaksi avainlajia.
• GitHubin henkilökohtaisen käyttöoikeustunnuksen — jolla on lukuoikeus repositorion issueihin. Jokainen tuonti todentautuu, koska haku kulkee GitHubin GraphQL-rajapinnan kautta ja GraphQL hylkää pyynnön ilman tokenia. Voit jättää sen pois vain silloin, kun Tracker hakee puolestasi: julkinen repositorio, asennuksella jolla on jaettu vara-token (isännöity eastagiletracker.com on sellainen; itse isännöidyllä asennuksella ei ole, ennen kuin sen ylläpitäjä asettaa GITHUB_IMPORT_PAT), eikä koskaan GitHub-to-EATin --engine direct -moottorilla. Katso Tokenit ja pyyntörajat.
• Node.js 22+ — vain vaiheen 3 GitHub-to-EAT-reitille. API-reitti ei tarvitse muuta kuin curlin.

1. Luo projekti

Projektin on oltava olemassa ennen agenttiavainta, ja sen on luonut ihminen: agenttiavaimet sidotaan yhteen projektiin jo myönnettäessä, eivätkä ne voi luoda projekteja. Tee se käyttöliittymässä tai omalla ea_user_…-avaimellasi:

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

Vastaus kantaa project_id:n, jota jokainen alla oleva kutsu tarvitsee.

2. Myönnä agenttiavain

Projektin omistaja luo agenttiavaimet kohdassa Projektin asetukset → Agentit. Valittu rooli ratkaisee, kuinka paljon tästä sivusta agentti pystyy tekemään itse, ja järkeviä vastauksia on kaksi:

• owner — yksi avain ajaa koko silmukan, tuonti mukaan lukien. Tuominen on vain omistajalle, koska tuonti kirjoittaa projektin muodon kokonaan uusiksi. owner-roolisen agentin myöntäminen edellyttää, että olet itse projektin omistaja: agentin rooli ei koskaan voi ylittää luojansa roolia.
• member — pienin oikeus. Agentti ottaa storyja, siirtää niitä, kommentoi ja liittää pull requesteja, mutta ei voi tuoda. Tuonnin ajat itse (vaihe 5) omalla avaimellasi ja luovutat taulun sen jälkeen agentille.

Kummassakin tapauksessa: älä jätä oletusarvoa. Uusi agenttiavain on viewer, kunnes sanot toisin, ja viewer lukee taulun mutta ei ota eikä siirrä storya — ja se on suurin osa tästä silmukasta.

Agenttiavaimilla on tässä merkitystä pääsyä laajemmin. Agenttiavain toimii nimettynä osallistujana yhdessä projektissa, joten jokainen sen luoma story, jokainen sen tekemä tilanmuutos ja jokainen sen kirjoittama kommentti kirjautuu historiassa sille agentille — erotettavissa omasta työstäsi eikä sekoittuneena siihen.

export TRACKER_TOKEN="ea_agent_xxxxx"

Anna agentin lukea /meta ennen mitään muuta:

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

Se vastaa kahteen kysymykseen, joita agentti muuten arvailisi: mihin projektiin avain on sidottu (auth.project_id) ja mitkä tilasiirtymät ovat sallittuja kullekin story-tyypille (transitions). Feature kulkee unstarted → started → finished → delivered → accepted; chore on vain unstarted → started → accepted. Kartan lukeminen voittaa sen kovakoodaamisen.

3. Tuo GitHub-to-EATilla

GitHub-to-EAT on East Agilen oma avoimen lähdekoodin tuontityökalu: MIT-lisensoitu komentorivityökalu, joka hoitaa koko täyttövaiheen — alla olevat vaiheet 4 ja 5 — yhdellä komennolla. Tartu siihen, kun ihminen istuu päätteen ääressä. Tartu sen alla olevaan API:in, kun agentti ajaa ilman valvontaa ja haluaa työn kahvan kyseltäväksi.

Se vaatii Node.js 22+ eikä sillä ole omia ajonaikaisia riippuvuuksia. Sitä ei ole vielä julkaistu npm:ään, joten asenna se repositoriosta:

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

Osoita se sitten vaiheessa 2 myönnettyyn avaimeen ja vaiheessa 1 luotuun projektiin:

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

Se tulostaa ensin vastaavuusselitteen — tarkalleen miten kukin valittu tyyppi laskeutuu — ja pyytää vahvistusta ennen kuin kirjoittaa mitään. Päätteen ulkopuolella, putkessa, CI:ssä tai agentissa ei ole paikkaa näyttää sitä kysymystä, joten ajon, joka kirjoittaisi, on annettava --yes; ilman sitä työkalu päättyy koodiin 2 eikä kirjoita mitään sen sijaan että arvaisi vastauksesi. Uudelleenajo on turvallista: jo tuotu ohitetaan, ei koskaan kahdenneta.

Lippu	Mitä se tekee
--dry-run	Esitarkistus, sitten tuloste suunnitelmasta jonka se toteuttaisi — montako storya se toisi, montako se ohittaisi jo olemassa olevina — eikä kirjoita mitään. Ei tarvitse --yes-lippua.
--include	Mitkä tyypit tuodaan, pilkuin eroteltuna: issues,prs,milestones,releases,deps. Oletus on issues, ja jokaisen valinnan on sisällettävä se. Nämä ovat samat mukaanotot kuin vaiheen 6 taulukossa.
--token	GitHubin henkilökohtainen käyttöoikeustunnuksesi (myös GITHUB_TOKEN ympäristössä tai .env-tiedostossa kelpaa). Se tarvitsee repo-oikeuden tai hienojakoisen Issues: Read -oikeuden kyseiseen repositorioon. Pakollinen yksityiselle repositoriolle, palvelimelle jolla ei ole jaettua vara-tokenia, ja aina --engine direct -moottorilla. Jätä se pois isännöidyn palvelun oletusmoottorilla, niin Tracker kuluttaa omaa jaettua budjettiaan — katso Tokenit ja pyyntörajat.
--engine	server, oletus, lähettää yhden /import/json-kutsun ja antaa Trackerin hakea, kartoittaa ja kirjoittaa. direct ajaa saman putken koneellasi ja kirjoittaa sen sijaan julkisen API:n kautta — se siis lukee GitHubia itse ja tarvitsee aina tokenin, päättyen muuten koodiin 2.
--states, --milestones, --story-type, --no-comments, --no-tasks	Rajaavat tai ohittavat kartoituksen yhdeksi ajoksi; mitään ei tallenneta. Jokainen niistä edellyttää --engine direct.

Aseta EAT_API_BASE ja EAT_APP_BASE osoittaaksesi sen itse isännöityyn tai paikalliseen Trackeriin; molemmat osoittavat oletuksena isännöityyn palveluun. README kantaa täyden lippuviitteen, päättymiskoodit ja vianetsinnän.

Kaikki alla oleva on sama tuonti kutsu kerrallaan ohjattuna, ja juuri sitä haluat, kun sen ajaa agentti.

4. Ensin kuiva-ajo

Tuominen on vain omistajalle — käytä owner-roolista agenttiavainta tai omaa avaintasi, jos jätit agentin rooliin member. Aja se ensin dry_run-lipulla, ennen kuin annat sen kirjoittaa mitään:

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

Kuiva-ajo hakee GitHubista, ratkaisee ja poistaa duplikaatit täsmälleen kuten oikea ajo, raportoi samat lukemat — imported, skipped, errors, unmatched — ja peruu sitten koko transaktion. Mitään ei jää jäljelle eikä yksikään valmistuneen tuonnin tapahtuma päädy audit-lokiisi. Se on halvin tapa huomata, että tarkoitit ottaa virstanpylväät mukaan tai että repositorio on isompi kuin luulit — kun se ei vielä maksa sinulle mitään.

Jokainen kutsu /import/json-päätepisteeseen on asynkroninen, kuiva-ajo mukaan lukien: päätepiste palauttaa 202 ja työn kahvan, ei tulosta, ja lukemat saapuvat työhön, kun kyselet sitä (vaihe 5). Kuiva-ajon työ saavuttaa tilan done kuten oikeakin; ero on siinä, ettei mitään kirjoitettu.

5. Aja tuonti

Poista dry_run ja lähetä uudelleen. Kuten aiemmin, päätepiste palauttaa 202 ja työn kahvan:

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

Kysele työtä, kunnes se saavuttaa lopputilan:

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

Tila kulkee pending → fetching → writing → done | failed. Vain kaksi viimeistä ovat lopputiloja: done kantaa tuloslukemat, failed kantaa virheviestin ja vakaan konekoodin, jonka mukaan voit haarautua. Kun haku sivuttaa, progress_current ja progress_total kertovat, millä sivulla ollaan — kannattaa näyttää, jos ihminen seuraa.

Tokenit. Anna "token": "github_pat_…". Jätä se pois, niin palvelin käyttää jaettua alustatokenia, joka lukee vain julkisia repositorioita ja jonka kulutus lasketaan kaikille asennuksen kutsujille — Tokenit ja pyyntörajat kertoo, mitä se sinulle maksaa. Kumpi token tahansa on käytössä, se ohjaa ylävirran GitHub-kutsuja eikä mitään muuta: sitä ei koskaan kirjata lokiin, ei audit-lokiin, ei tallenneta eikä kaiuteta takaisin vastauksessa tai virheessä.

Uudelleenajo on turvallista. Jo tuotu rivi tunnistetaan lähde-id:nsä perusteella ja ohitetaan, ei kahdenneta. Toinen tuonti täydentää taulun sillä, mitä ensimmäisen jälkeen on ilmestynyt.

6. Mitä taululle laskeutuu

Issuet tuodaan oletuksena. Kaikki muu on mukaanotettavaa, yksi lippu tyyppiä kohti:

GitHubista	Muuttuu	Lippu
Issue	Story. Avoin → unstarted Backlogissa. Suljettu → accepted, tai rejected kun GitHub kertoo issuen suljetun tilaan not_planned tai duplicate (story kantaa silloin vastaavaa tunnistetta).	oletus
Issuen rungon tarkistuslista	Tehtävät — jokainen rivi - [ ] / - [x] muuttuu yhdeksi tehtäväksi rungon järjestyksessä, ja [x] saapuu valmiina. Tarkistuslista jää myös kuvaukseen.	oletus
Tunnisteet	Tunnisteet, siirtyvät sellaisenaan.	oletus
Pull request	Story, jolla on tunniste pull-request. Avoin → started, yhdistetty → accepted, suljettu ilman yhdistämistä → rejected.	include_pull_requests
Virstanpylväs	Epic, nimetty virstanpylvään mukaan ja kahdennuksista siivottu otsikon perusteella — kaksi saman virstanpylvään issueta päätyvät yhteen epiciin. Lipun ollessa pois päältä se kulkee mukana tunnisteena milestone:<otsikko>.	include_milestones
Julkaisu	Julkaisustory. Julkaistu → accepted, luonnos → unstarted.	include_releases
Issuen riippuvuus	Este storylla. Vain issuet, ei koskaan pull requesteja.	include_dependencies

Story-tyyppi päätellään, kun issue ei sitä kerro. Tunniste, joka sisältää bug, fix tai defect — tai otsikko, joka alkaa sanalla fix tai bug — tekee siitä bugin; chore, maintenance, devops tai infra tekevät siitä choren; kaikki muu on feature. Se kannattaa tietää ennen tuontia, koska East Agile Trackerissa vain featureilla on pointteja ja vain featuret syöttävät velocityä. Katso Johdanto → Storyt.

7. Agentti työstää storyn

Nyt taululla on historiaa ja agentilla avain. Silmukka tästä eteenpäin on neljä kutsua.

Etsi story tai kirjoita uusi. Suodata taulusta jotain poimittavaa:

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

import_source=github rajaa tuloksen siihen, mitä tuonti toi. Jos agentti on löytänyt työtä, jota repositorio ei koskaan tallentanut, se luo storyn itse — katso API-opas → Luo story.

Ota se itselle. Agentti lisää itsensä omistajaksi lähettämällä tyhjän rungon:

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

Tyhjä runko tarkoittaa kutsujaa, joten agentin ei tarvitse tietää omaa id:tään. Taulu näyttää nyt agentin omistajana, ja siitä seuraava ihminen tietää, että työ on otettu.

Aloita se.

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

Sitten agentti menee ja tekee työn — lukee repositorion, kirjoittaa koodin, avaa pull requestin. Se osuus tapahtuu koodityökalussasi, ei täällä.

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

GitHubin pull request -URL tunnistetaan sellaiseksi — sinun ei tarvitse sanoa sitä. Story ja sen sulkeva koodi ovat nyt yhden klikkauksen päässä toisistaan, molempiin suuntiin.

Päätä se. Siirry tilaan finished ja pysähdy siihen. Featurella on vielä delivered ja accepted edessään, ja ne ovat katselmusportit: joku muu kuin agentti päättää, että työ on oikein. Chorella ei ole sellaista porttia — started → accepted on koko sen jäljellä oleva polku.

Tokenit ja pyyntörajat

Jokainen tuonti todentautuu. Issueiden, kommenttien ja pull requestien haku kulkee GitHubin GraphQL-rajapinnan kautta, ja GraphQL hylkää pyynnön ilman tokenia — anonyymia tasoa ei ole, ei julkisella eikä yksityisellä repositoriolla. Kysymys ei koskaan ole lähteekö token GitHubiin, vaan vain kenen.

Oma tokenisi

Anna token tuontikutsussa tai --token GitHub-to-EATille. Hienojakoinen henkilökohtainen käyttöoikeustunnus, jolla on lukuoikeus repositorion issueihin, riittää. Se ohjaa ylävirran GitHub-kutsuja eikä mitään muuta: sitä ei koskaan kirjata lokiin, ei audit-lokiin, ei tallenneta eikä kaiuteta takaisin vastauksessa tai virheessä.

Tuo oma mukanasi kaikkeen demoa suurempaan. Silloin kulutat budjettia, johon kukaan muu ei koske, eikä mikään esitarkistus voi hylätä sinua jonkun toisen tuonnin takia.

--engine direct ei jätä sinulle vaihtoehtoa. Se moottori lukee GitHubia koneeltasi eikä Trackerin kautta, joten palvelimen token on tavoittamattomissa; tokeniton ajo päättyy koodiin 2 ja käyttövirheeseen ennen kuin se hakee tai kirjoittaa mitään. GITHUB_TOKEN ympäristössäsi tai .env-tiedostossasi kelpaa samoin kuin --token.

Tokenin pakottaa issueiden läpikäynti, ei koko moottori. direct lukee issuet, kommentit ja pull requestit GraphQL:n yli, jolla ei ole anonyymiä tilaa; REST:iä se koskee vain release-listaukseen ja ilmaiseen /rate_limit-kyselyyn. Työkalu toimittaa yhä vanhemman anonyymin REST-hakijan, joka vei julkisen repositorion tuonnin läpi 60 tunnissa -budjetilla, mutta mikään CLI-polku ei enää saavuta sitä ja se on määrä poistaa — pidä siis --token pakollisena direct-moottorille.

Asennuksen jaettu token

Älä lähetä token-kenttää, niin palvelin käyttää ylläpitäjän määrittämää alustatokenia (GITHUB_IMPORT_PAT). Mukana tulee kolme rajoitusta:

• Se on valinnainen määritys. Isännöity eastagiletracker.com tarjoaa sellaisen, joten tokeniton julkisen repositorion tuonti toimii siellä. Itse isännöidyllä asennuksella — ladatulla binäärillä — ei ole sellaista, ennen kuin sen ylläpitäjä asettaa ympäristöön GITHUB_IMPORT_PAT, ja siihen asti se hylkää jokaisen tokenittoman tuonnin virheellä 400 import_github_no_token.
• Se lukee vain julkisia repositorioita. Isännöity palvelu myöntää sen vain lukuoikeudella julkisiin repositorioihin, joten yksityinen repositorio vaatii aina oman tokenisi.
• Kaikki asennuksen kutsujat jakavat yhden budjetin. Ennen kuin tokeniton tuonti käynnistyy, palvelin lukee jaetun tokenin jäljellä olevat GraphQL-pisteet ja hylkää alle 500:n virheellä 400 import_github_shared_quota_low. Kesken tuonnin loppuva budjetti kaataa työn virheeseen import_github_rate_limited_platform. Molemmat viestit nimeävät saman korjauksen: anna oma tokenisi.

Mitä token tuo

GitHub mittaa kahta rajapintaansa erikseen, ja todentamaton katto on kaksi kertaluokkaa matalampi.

GitHub-rajapinta	Käytetään	Tokenilla	Ilman tokenia
GraphQL	Issuet, kommentit, pull requestit, ali-issuet, riippuvuudet	5 000 pistettä tunnissa, pisteytettynä kyselyn palauttamien solmujen mukaan	Hylätty — GraphQLissa ei ole anonyymiä tasoa
REST	Julkaisut (include_releases) ja /rate_limit-esitarkistus	5 000 pyyntöä tunnissa	60 pyyntöä tunnissa, laskettuna IP-osoitetta kohti ja jaettuna kaikkien sen takana olevien kesken

Tuonti ei koskaan putoa tuolle 60 tunnissa -tasolle: kun lähetettävää tokenia ei ole, pyyntö hylätään etukäteen sen sijaan että sitä yritettäisiin anonyymisti uudelleen. Luku merkitsee sen kannalta, mitä teet tuonnin ympärillä — GitHubia suoraan lukeva skripti tai muiden asiakkaiden kanssa samassa verkossa oleva komentotulkki kuluttaa 60 pyyntöä sekunneissa.

Lue jäljellä oleva budjettisi milloin tahansa; GET /rate_limit on vapautettu molemmista rajoista, joten tarkistus ei maksa mitään:

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

GraphQL-pisteet eivät ole pyyntöjä. GitHub pisteyttää kyselyn sen palauttamien solmujen mukaan, joten yksi sivullinen 100 issueta kommentteineen ja vastuuhenkilöineen maksaa monta pistettä, ja iso repositorio kuluttaa tuntibudjetin paljon harvemmilla kutsuilla kuin REST-ajan luvut antavat ymmärtää. --dry-run (vaihe 3) ja dry_run (vaihe 4) maksavat kumpikin saman verran pisteitä kuin oikea haku — juuri se tekee niiden lukemista luotettavia — joten varaa kaksi kierrosta, kun esitarkistat ison tuonnin.

Mihin seuraavaksi

• API-opas — hakukielioppi, tapahtumavirta, joukkosiirtymät, idempotentit kirjoitukset ja loput pinnasta.
• Käyttöohjeet — samat toiminnot käyttöliittymästä, ja ne kymmenen muuta tuontityökalua.
• Johdanto — miksi tilakone ja neljä story-tyyppiä ovat juuri tämän muotoisia.
• GitHub-to-EAT — tuontityökalun oma repositorio: jokainen lippu, molemmat moottorit ja miten siihen voi osallistua.