Fyll ett projekt från ett GitHub-repo

Rikta en agent mot ett GitHub-repository så får du tillbaka en fungerande board: varje issue som en story, i det tillstånd dess historik säger att den ska ha, med checklistor, etiketter och milstolpar överförda. Sedan plockar samma agent upp en story, gör anspråk på den, för den genom tillståndsmaskinen och länkar den pull request den öppnade.

Den här sidan beskriver hela den slingan. Fyllnadssteget har två vägar: GitHub-to-EAT, East Agiles öppna importverktyg, gör det med ett enda kommando (steg 3); import-API:et gör samma arbete anrop för anrop (steg 4 och 5), vilket är det en agent styr när den vill ha jobbets handtag. Allt därefter går via API:et, eftersom hela poängen är att en agent ska klara resten utan tillsyn.

Detta är ingen separat »AI-import«. Fyllnadssteget är samma GitHub-import som du kan köra för hand från Projektinställningar → Importera / Exportera, beskriven i Bruksanvisning → Importera från andra trackers. Agenten anropar samma endpoint som du skulle ha gjort. Det den här sidan lägger till är allt runt omkring: vem som håller nyckeln, hur du kontrollerar importen innan den skriver, och vad agenten gör med boarden när den väl finns.

GitHub-källan på fliken Import / Export: ägare och repository ifyllda, token tom, pull requests och milstolpar ikryssade

Vad du behöver

Ett projekt — och en session eller en ea_user_…-nyckel att skapa det med.
En agentnyckel — en ea_agent_…-nyckel begränsad till det projektet. Vilken roll den behöver beror på hur mycket av slingan du vill att agenten kör; se steg 2. Se även API-guide → Två sorters nycklar.
En personlig GitHub-åtkomsttoken — med läsrättighet till repositoryts issues. Varje import autentiserar sig, eftersom hämtningen går via GitHubs GraphQL-API och GraphQL avvisar en förfrågan utan token. Du kan utelämna den bara när Trackern hämtar för din räkning: ett publikt repository, på en driftsättning som har en delad reservtoken (den hostade eastagiletracker.com har en; en självhostad installation har ingen förrän dess operatör sätter GITHUB_IMPORT_PAT), och inte med GitHub-to-EATs --engine direct. Se Token och hastighetsgränser.
Node.js 22+ — endast för GitHub-to-EAT-vägen i steg 3. API-vägen behöver inget mer än curl.

1. Skapa projektet

Projektet måste finnas innan agentnyckeln gör det, och det måste skapas av en människa: agentnycklar binds till ett projekt när de utfärdas och kan inte starta upp projekt. Skapa det i gränssnittet, eller med din egen ea_user_…-nyckel:

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

Svaret bär det project_id som varje anrop nedan behöver.

2. Utfärda en agentnyckel

En projektägare skapar agentnycklar i Projektinställningar → Agenter. Rollen du väljer avgör hur mycket av den här sidan agenten klarar på egen hand, och det finns två rimliga svar:

owner — en enda nyckel kör hela slingan, import inräknad. Att importera är förbehållet ägaren, eftersom en import skriver om projektets form i sin helhet. Att utfärda en agent med rollen owner kräver att du själv är projektägare: en agents roll kan aldrig överstiga dess skapares.
member — minsta privilegium. Agenten gör anspråk på stories, flyttar dem, kommenterar och länkar pull requests, men kan inte importera. Importen kör du själv (steg 5) med din egen nyckel och lämnar sedan över boarden till agenten.

Hur du än gör: låt den inte stå kvar på standardvärdet. En ny agentnyckel är viewer tills du säger något annat, och en viewer kan läsa boarden men varken göra anspråk på eller flytta en story — vilket är merparten av den här slingan.

Agentnycklar spelar roll här av ett skäl bortom åtkomst. En agentnyckel agerar som namngiven deltagare i ett enda projekt, så varje story den skapar, varje tillståndsbyte den gör och varje kommentar den skriver tillskrivs den agenten i historiken — särskiljbar från ditt eget arbete i stället för hopblandad med det.

export TRACKER_TOKEN="ea_agent_xxxxx"

Låt agenten läsa /meta före allt annat:

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

Det besvarar de två frågor agenten annars skulle gissa sig till: vilket projekt nyckeln är bunden till (auth.project_id), och vilka tillståndsbyten som är tillåtna per storytyp (transitions). En feature går unstarted → started → finished → delivered → accepted; en chore är bara unstarted → started → accepted. Att läsa kartan slår att hårdkoda den.

3. Importera med GitHub-to-EAT

GitHub-to-EAT är East Agiles eget öppna importverktyg: ett MIT-licensierat kommandoradsverktyg som gör hela fyllnadssteget — steg 4 och 5 nedan — med ett kommando. Ta till det när en människa sitter vid en terminal. Ta till API:et under det när en agent styr utan tillsyn och vill ha jobbets handtag att polla.

Det kräver Node.js 22+ och har inga egna körtidsberoenden. Det är ännu inte publicerat på npm, så installera det från repositoryt:

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

Rikta det sedan mot nyckeln du utfärdade i steg 2 och projektet du gjorde i steg 1:

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

Det skriver först ut en mappningslegend — exakt hur varje vald typ kommer att landa — och ber om bekräftelse innan det skriver något. Utanför en terminal, i ett rör, i CI eller i en agent finns ingenstans att visa den frågan, så en körning som skulle skriva måste skicka --yes; utan det avslutas verktyget med 2 och skriver ingenting i stället för att gissa ditt svar. Att köra om är säkert: det som redan importerats hoppas över, aldrig dubbleras.

Flagga	Vad den gör
`--dry-run`	Förkontroll, sedan utskrift av planen den skulle genomföra — hur många stories den skulle importera, hur många den skulle hoppa över som redan befintliga — och skriver ingenting. Behöver inget `--yes`.
`--include`	Vilka typer som ska importeras, kommaseparerat: `issues,prs,milestones,releases,deps`. Standard är `issues`, och varje urval måste innehålla det. Det är samma tillval som tabellen i steg 6.
`--token`	Din personliga GitHub-åtkomsttoken (`GITHUB_TOKEN` i miljön eller i en `.env` räknas också). Den behöver `repo`, eller finkornigt Issues: Read, på det repositoryt. Krävs för ett privat repository, för en server utan delad reservtoken, och alltid för `--engine direct`. Utelämna den på den hostade tjänstens standardmotor så spenderar Trackern sin egen delade budget — se Token och hastighetsgränser.
`--engine`	`server`, standardvalet, skickar ett `/import/json`-anrop och låter Trackern hämta, mappa och skriva. `direct` kör samma pipeline på din maskin och skriver i stället via det publika API:et — den läser alltså GitHub själv och behöver alltid en token, annars avslutas den med `2`.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Begränsar eller åsidosätter mappningen för en körning; inget sparas. Var och en av dem medför `--engine direct`.

Sätt EAT_API_BASE och EAT_APP_BASE för att rikta det mot en självhostad eller lokal Tracker; båda pekar som standard på den hostade tjänsten. README bär den fullständiga flaggreferensen, avslutningskoderna och felsökningen.

Allt nedan är samma import styrd anrop för anrop, vilket är det du vill ha när en agent kör den.

4. Torrkörning först

Att importera är förbehållet ägaren — använd en agentnyckel med rollen owner, eller din egen nyckel om du lämnade agenten som member. Kör den först med dry_run, innan du låter den skriva något:

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

En torrkörning hämtar från GitHub, resolvar och av-dubblerar precis som den riktiga, rapporterar samma räknare — imported, skipped, errors, unmatched — och rullar sedan tillbaka hela transaktionen. Ingenting består och ingen händelse om slutförd import når din revisionslogg. Det är det billigaste sättet att upptäcka att du menade att ta med milstolpar, eller att ett repo är större än du trodde, medan det fortfarande inte kostar dig något.

Varje anrop till /import/json är asynkront, torrkörningen inräknad: endpointen returnerar 202 med ett jobbhandtag, inte ett resultat, och räknarna kommer på jobbet när du pollar det (steg 5). En torrkörnings jobb når done precis som ett riktigt; skillnaden är att ingenting skrevs.

5. Kör importen

Ta bort dry_run och skicka igen. Som tidigare returnerar endpointen 202 med ett jobbhandtag:

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

Polla jobbet tills det når ett sluttillstånd:

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

Statusen går pending → fetching → writing → done | failed. Bara de två sista är sluttillstånd: done bär resultaträknarna, failed bär ett felmeddelande och en stabil maskinkod du kan förgrena på. Medan hämtningen paginerar säger progress_current och progress_total vilken sida den är på — värt att visa om en människa tittar på.

Token. Skicka "token": "github_pat_…". Utelämna den så sätter servern in den delade plattforms-tokenen, som bara läser publika repositoryn och räknas av mot varje anropare på driftsättningen — Token och hastighetsgränser täcker vad det kostar dig. Vilken token som än används driver den bara de utgående GitHub-anropen och inget annat: den loggas aldrig, revisionsloggas aldrig, lagras aldrig och ekas aldrig tillbaka i ett svar eller ett fel.

Att köra om är säkert. En rad som redan importerats matchas på sitt käll-id och hoppas över, inte dubbleras. En andra import fyller på boarden med det som dykt upp sedan den första.

6. Vad som landar på boarden

Issues importeras som standard. Allt annat är tillval, en flagga per typ:

Från GitHub	Blir	Flagga
Issue	En story. Öppen → unstarted i Backlog. Stängd → accepted, eller rejected när GitHub säger att issuen stängdes som `not_planned` eller `duplicate` (storyn bär då en matchande etikett).	standard
Checklista i issue-texten	Tasks — varje rad `- [ ]` / `- [x]` blir en task i textens ordning, där `[x]` anländer färdig. Checklistan står kvar i beskrivningen också.	standard
Etiketter	Etiketter, överförda som de är.	standard
Pull request	En story med etiketten `pull-request`. Öppen → started, mergad → accepted, stängd utan merge → rejected.	`include_pull_requests`
Milstolpe	En epic, med milstolpens namn och av-dubblerad på titel — två issues som delar milstolpe landar i samma epic. Med flaggan av följer den i stället med som etiketten `milestone:<titel>`.	`include_milestones`
Release	En release-story. Publicerad → accepted, utkast → unstarted.	`include_releases`
Issue-beroende	En blockerare på storyn. Bara issues, aldrig pull requests.	`include_dependencies`

Storytypen härleds när issuen inte säger den. En etikett som innehåller bug, fix eller defect — eller en titel som börjar med fix eller bug — gör den till en bug; chore, maintenance, devops eller infra gör den till en chore; allt annat är en feature. Det är värt att veta före import, för i East Agile Tracker bär bara features points och bara features matar velocity. Se Introduktion → Stories.

En projekttavla direkt efter import av exempelrepositoryt: issues som storys med sina etiketter, milstolpar som epics och GitHub-personer som ägare

7. Agenten arbetar med en story

Nu har boarden historik och agenten en nyckel. Slingan härifrån är fyra anrop.

Hitta en story, eller skriv en. Filtrera boarden efter något att plocka upp:

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

import_source=github avgränsar till det importen tog med sig. Har agenten hittat arbete som repot aldrig fångade skapar den storyn i stället — se API-guide → Skapa en story.

Gör anspråk på den. En agent lägger till sig själv som ägare genom att posta en tom 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 '{}'

En tom body betyder anroparen, så agenten behöver inte känna till sitt eget id. Boarden visar nu agenten som ägare, och det är så en människa som tittar på vet att arbetet är taget.

Starta den.

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

Sedan går agenten och gör arbetet — läser repot, skriver koden, öppnar pull requesten. Den delen sker i ditt utvecklingsverktyg, inte här.

Bifoga pull requesten.

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

En GitHub-pull-request-URL känns igen som en sådan — du behöver inte säga det. Storyn och koden som stänger den ligger nu ett klick från varandra, i båda riktningarna.

Avsluta den. Gå till finished och stanna där. En feature har delivered och accepted kvar framför sig, och det är granskningsgrindarna: någon annan än agenten avgör att arbetet är rätt. En chore har ingen sådan grind — started → accepted är hela dess återstående väg.

En importerad stängd issue vars CODE-avsnitt länkar till den pull request som åtgärdade den, med GitHub-kommentarerna bredvid

Token och hastighetsgränser

Varje import autentiserar sig. Hämtningen av issues, kommentarer och pull requests går via GitHubs GraphQL-API, och GraphQL avvisar en förfrågan utan token — det finns ingen anonym nivå, varken på ett publikt repository eller ett privat. Frågan är aldrig om en token går till GitHub, bara vems.

Din egen token

Skicka token på importanropet, eller --token till GitHub-to-EAT. En finkornig personlig åtkomsttoken med läsrättighet till repositoryts issues räcker. Den driver de utgående GitHub-anropen och inget annat: den loggas aldrig, revisionsloggas aldrig, lagras aldrig och ekas aldrig tillbaka i ett svar eller ett fel.

Ta med din egen till allt bortom en demo. Då spenderar du en budget ingen annan rör, och ingen förkontroll kan avvisa dig på grund av någon annans import.

--engine direct lämnar dig inget val. Den motorn läser GitHub från din maskin i stället för genom Trackern, så serverns token är utom räckhåll; en körning utan token avslutas med 2 och ett användningsfel innan den hämtar eller skriver något. GITHUB_TOKEN i din miljö eller din .env räknas, precis som --token.

Det är genomgången av issues som kräver token, inte hela motorn. direct läser issues, kommentarer och pull requests över GraphQL, som saknar anonymt läge; REST rör den bara för release-listan och den kostnadsfria /rate_limit-sonderingen. Verktyget levererar fortfarande en äldre anonym REST-hämtare som klarade en import av ett publikt repository inom budgeten på 60 i timmen, men ingen väg i CLI:t når den längre och den ska tas bort — betrakta därför --token som obligatorisk för direct.

Driftsättningens delade token

Skicka ingen token så sätter servern in den plattforms-token som dess operatör konfigurerat (GITHUB_IMPORT_PAT). Tre gränser följer med:

Det är valfri konfiguration. Den hostade eastagiletracker.com tillhandahåller en, så en import av ett publikt repository utan token fungerar där. En självhostad installation — den nedladdade binären — har ingen förrän dess operatör sätter GITHUB_IMPORT_PAT i miljön, och fram till dess avvisar den varje import utan token med 400 import_github_no_token.
Den läser bara publika repositoryn. Den hostade tjänsten utfärdar den skrivskyddad över publika repon, så ett privat repository behöver alltid din egen token.
Alla anropare på driftsättningen delar en budget. Innan en import utan token körs läser servern den delade tokenens återstående GraphQL-poäng och avvisar med 400 import_github_shared_quota_low under 500. En budget som tar slut mitt i importen får jobbet att misslyckas med import_github_rate_limited_platform. Båda meddelandena pekar på samma åtgärd: tillhandahåll din egen token.

Vad token ger dig

GitHub mäter sina två API:er var för sig, och det oautentiserade taket ligger två storleksordningar lägre.

GitHub-API	Används för	Med token	Utan token
GraphQL	Issues, kommentarer, pull requests, under-issues, beroenden	5 000 poäng per timme, poängsatta på de noder en fråga returnerar	Avvisad — GraphQL har ingen anonym nivå
REST	Releaser (`include_releases`) och `/rate_limit`-förkontrollen	5 000 förfrågningar per timme	60 förfrågningar per timme, räknade per IP-adress och delade med alla bakom den

En import faller aldrig tillbaka på den nivån om 60 per timme: utan en token att skicka avvisas förfrågan i förväg i stället för att göras om anonymt. Siffran spelar roll för det du gör runt importen — ett skript som läser GitHub direkt, eller ett skal i samma nät som andra klienter, förbrukar 60 förfrågningar på sekunder.

Läs din återstående budget när du vill; GET /rate_limit är undantagen från båda gränserna, så kontrollen kostar ingenting:

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

GraphQL-poäng är inte förfrågningar. GitHub poängsätter en fråga på de noder den returnerar, så en sida med 100 issues jämte deras kommentarer och tilldelade kostar många poäng, och ett stort repository gör av med timbudgeten på långt färre anrop än REST-erans siffror antyder. --dry-run (steg 3) och dry_run (steg 4) kostar var för sig samma poäng som den riktiga hämtningen — det är det som gör deras räknare pålitliga — så räkna med två pass när du förbereder en stor import.

Vart du går härnäst

API-guide — sökgrammatiken, händelseströmmen, massövergångar, idempotenta skrivningar och resten av ytan.
Bruksanvisning — samma operationer från gränssnittet, och de tio andra importverktygen.
Introduktion — varför tillståndsmaskinen och de fyra storytyperna har den här formen.
GitHub-to-EAT — importverktygets eget repository: varje flagga, båda motorerna, och hur du bidrar till det.