Fyld et projekt fra et GitHub-repo

Peg en agent mod et GitHub-repository, og du får et fungerende board tilbage: hver issue som en historie, i den tilstand dens historik siger den skal have, med tjeklister, labels og milepæle ført med over. Derefter tager den samme agent en historie op, gør krav på den, fører den gennem tilstandsmaskinen og linker den pull request, den åbnede.

Denne side gennemgår hele den løkke. Udfyldningstrinnet har to veje: GitHub-to-EAT, East Agiles open source-importør, klarer det med én kommando (trin 3); import-API’et gør det samme arbejde kald for kald (trin 4 og 5), og det er dét en agent styrer, når den vil have jobbets håndtag. Alt derefter kører på API’et, for pointen er netop, at en agent kan klare resten uden opsyn.

Dette er ikke en separat »AI-import«. Udfyldningstrinnet er den samme GitHub-importør, du kan køre i hånden fra Projektindstillinger → Importér / Eksportér, beskrevet i Betjeningsvejledning → Import fra andre trackere. Agenten kalder det samme endpoint, som du ville. Det, denne side lægger til, er alt rundt om: hvem der holder nøglen, hvordan du kontrollerer importen, før den skriver, og hvad agenten gør med boardet, når det først findes.

GitHub-kilden på fanen Import / Export: ejer og repository udfyldt, token tomt, pull requests og milepæle markeret

Hvad du skal bruge

Et projekt — og en session eller en ea_user_…-nøgle at oprette det med.
En agent-nøgle — en ea_agent_…-nøgle afgrænset til det projekt. Hvilken rolle den skal have, afhænger af, hvor meget af løkken du vil lade agenten køre; se trin 2. Se også API-guide → To slags nøgler.
Et personligt GitHub-adgangstoken — med læseadgang til repositoriets issues. Enhver import autentificerer sig, fordi hentningen kører på GitHubs GraphQL-API, og GraphQL afviser en forespørgsel uden token. Du kan kun udelade det, når Trackeren henter på dine vegne: et offentligt repository, på et deployment der har et delt reservetoken (den hostede eastagiletracker.com har et; en selvhostet installation har ingen, før dens operatør sætter GITHUB_IMPORT_PAT), og ikke med GitHub-to-EATs --engine direct. Se Tokens og hastighedsgrænser.
Node.js 22+ — kun til GitHub-to-EAT-vejen i trin 3. API-vejen har ikke brug for andet end curl.

1. Opret projektet

Projektet skal findes, før agent-nøglen gør, og det skal oprettes af et menneske: agent-nøgler bindes til ét projekt, når de udstedes, og kan ikke starte projekter op. Opret det i brugerfladen, eller med din egen ea_user_…-nøgle:

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ærer det project_id, som hvert kald nedenfor har brug for.

2. Udsted en agent-nøgle

En projektejer opretter agent-nøgler under Projektindstillinger → Agenter. Den rolle, du vælger, afgør, hvor meget af denne side agenten kan klare selv, og der er to fornuftige svar:

owner — én nøgle kører hele løkken, import inklusive. Import er kun for ejeren, fordi en import omskriver projektets form under ét. At udstede en agent med rollen owner kræver, at du selv er projektejer: en agents rolle kan aldrig overstige dens skabers.
member — mindste privilegium. Agenten gør krav på historier, flytter dem, kommenterer og linker pull requests, men kan ikke importere. Importen kører du selv (trin 5) med din egen nøgle og overdrager derefter boardet til agenten.

Uanset hvad: lad det ikke stå på standardværdien. En ny agent-nøgle er viewer, indtil du siger andet, og en viewer kan læse boardet, men hverken gøre krav på eller flytte en historie — og det er det meste af denne løkke.

Agent-nøgler betyder noget her af en grund, der rækker ud over adgang. En agent-nøgle handler som navngiven deltager i ét enkelt projekt, så hver historie den opretter, hvert tilstandsskift den foretager og hver kommentar den skriver tilskrives den agent i historikken — til at skelne fra dit eget arbejde frem for smeltet sammen med det.

export TRACKER_TOKEN="ea_agent_xxxxx"

Lad agenten læse /meta før alt andet:

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

Det besvarer de to spørgsmål, agenten ellers ville gætte på: hvilket projekt nøglen er bundet til (auth.project_id), og hvilke tilstandsskift der er lovlige for hver historietype (transitions). En feature løber unstarted → started → finished → delivered → accepted; en chore er blot unstarted → started → accepted. At læse kortet slår at hardkode det.

3. Importér med GitHub-to-EAT

GitHub-to-EAT er East Agiles eget open source-importværktøj: et MIT-licenseret kommandolinjeværktøj, der klarer hele udfyldningstrinnet — trin 4 og 5 nedenfor — med én kommando. Grib til det, når et menneske sidder ved en terminal. Grib til API’et under det, når en agent styrer uden opsyn og vil have jobbets håndtag at polle på.

Det kræver Node.js 22+ og har ingen egne kørselsafhængigheder. Det er endnu ikke udgivet på npm, så installér det fra repositoriet:

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

Peg det derefter mod nøglen fra trin 2 og projektet fra trin 1:

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

Det udskriver først en tilknytningsforklaring — præcis hvordan hver valgt type vil lande — og beder om bekræftelse, før det skriver noget. Uden for en terminal, i en pipe, i CI eller i en agent er der ingen steder at vise den prompt, så en kørsel, der ville skrive, skal sende --yes; uden det afslutter værktøjet med 2 og skriver intet frem for at gætte dit svar. At køre igen er sikkert: det, der allerede er importeret, springes over, aldrig dubleres.

Flag	Hvad det gør
`--dry-run`	Forkontrol, derefter udskrift af den plan, det ville gennemføre — hvor mange historier det ville importere, hvor mange det ville springe over som allerede til stede — og skriver intet. Kræver ikke `--yes`.
`--include`	Hvilke typer der skal importeres, kommasepareret: `issues,prs,milestones,releases,deps`. Standard er `issues`, og ethvert udvalg skal indeholde det. Det er de samme tilvalg som tabellen i trin 6.
`--token`	Dit personlige GitHub-adgangstoken (`GITHUB_TOKEN` i miljøet eller i en `.env` tæller også). Det kræver `repo`, eller finkornet Issues: Read, på det repository. Påkrævet for et privat repository, for en server uden delt reservetoken, og altid for `--engine direct`. Udelad det på den hostede tjenestes standardmotor, og Trackeren bruger sit eget delte budget — se Tokens og hastighedsgrænser.
`--engine`	`server`, standardvalget, sender ét `/import/json`-kald og lader Trackeren hente, tilknytte og skrive. `direct` kører den samme pipeline på din maskin og skriver i stedet gennem det offentlige API — den læser altså GitHub selv og kræver altid et token, ellers afslutter den med `2`.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Indsnævrer eller tilsidesætter tilknytningen for én kørsel; intet gemmes. Hver af dem medfører `--engine direct`.

Sæt EAT_API_BASE og EAT_APP_BASE for at pege det mod en selvhostet eller lokal Tracker; begge peger som standard på den hostede tjeneste. README bærer den fulde flagreference, afslutningskoderne og fejlsøgningen.

Alt nedenfor er den samme import styret kald for kald, hvilket er det, du vil have, når en agent kører den.

4. Tørkørsel først

Import er kun for ejeren — brug en agent-nøgle med rollen owner, eller din egen nøgle, hvis du lod agenten stå som member. Kør den først med dry_run, før du lader den skrive noget:

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 tørkørsel henter fra GitHub, resolver og de-duplikerer nøjagtigt som den rigtige, rapporterer de samme tal — imported, skipped, errors, unmatched — og ruller derefter hele transaktionen tilbage. Intet består, og ingen hændelse om fuldført import når din revisionslog. Det er den billigste måde at finde ud af, at du mente at tage milepæle med, eller at et repo er større end du troede, mens det stadig ikke koster dig noget.

Hvert kald til /import/json er asynkront, tørkørslen inklusive: endpointet returnerer 202 med et jobhåndtag, ikke et resultat, og tallene kommer på jobbet, når du poller det (trin 5). En tørkørsels job når done ligesom et rigtigt; forskellen er, at intet blev skrevet.

5. Kør importen

Fjern dry_run og send igen. Som før returnerer endpointet 202 med et jobhåndtag:

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

Poll jobbet, indtil det når en sluttilstand:

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

Statussen løber pending → fetching → writing → done | failed. Kun de to sidste er sluttilstande: done bærer resultattallene, failed bærer en fejlbesked og en stabil maskinkode, du kan forgrene på. Mens hentningen paginerer, fortæller progress_current og progress_total, hvilken side den er på — værd at vise, hvis et menneske ser med.

Tokens. Send "token": "github_pat_…". Udelad det, og serveren indsætter det delte platform-token, som kun læser offentlige repositories og afregnes på tværs af alle kaldere på deploymentet — Tokens og hastighedsgrænser dækker, hvad det koster dig. Uanset hvilket token der bruges, driver det de opstrøms GitHub-kald og intet andet: det logges aldrig, revisionslogges aldrig, gemmes aldrig og ekkoes aldrig tilbage i et svar eller en fejl.

At køre igen er sikkert. En række, der allerede var importeret, matches på sit kilde-id og springes over, ikke dubleres. En anden import fylder boardet op med det, der er dukket op siden den første.

6. Hvad der lander på boardet

Issues importeres som standard. Alt andet er tilvalg, ét flag pr. type:

Fra GitHub	Bliver til	Flag
Issue	En historie. Åben → unstarted i Backlog. Lukket → accepted, eller rejected når GitHub siger, at issuen blev lukket som `not_planned` eller `duplicate` (historien bærer da en tilsvarende label).	standard
Tjekliste i issue-teksten	Opgaver — hver linje `- [ ]` / `- [x]` bliver til én opgave i tekstens rækkefølge, hvor `[x]` ankommer færdig. Tjeklisten bliver også stående i beskrivelsen.	standard
Labels	Labels, ført med uændret.	standard
Pull request	En historie med labelen `pull-request`. Åben → started, merget → accepted, lukket uden merge → rejected.	`include_pull_requests`
Milepæl	En epic, navngivet efter milepælen og de-dupliceret på titel — to issues, der deler en milepæl, lander i én epic. Med flaget slået fra følger den i stedet med som labelen `milestone:<titel>`.	`include_milestones`
Release	En release-historie. Udgivet → accepted, kladde → unstarted.	`include_releases`
Issue-afhængighed	En blokering på historien. Kun issues, aldrig pull requests.	`include_dependencies`

Historietypen udledes, når issuen ikke siger den. En label, der indeholder bug, fix eller defect — eller en titel, der begynder med fix eller bug — gør den til en bug; chore, maintenance, devops eller infra gør den til en chore; alt andet er en feature. Det er værd at vide inden import, for i East Agile Tracker bærer kun features points, og kun features fodrer velocity. Se Introduktion → Historier.

En projekttavle lige efter import af eksempel-repositoryet: issues som historier med deres etiketter, milepæle som epics og GitHub-personer som ejere

7. Agenten arbejder på en historie

Nu har boardet historik, og agenten har en nøgle. Løkken herfra er fire kald.

Find en historie, eller skriv en. Filtrér boardet efter noget at tage op:

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

import_source=github afgrænser til det, importen bragte ind. Har agenten fundet arbejde, som repoet aldrig fangede, opretter den historien i stedet — se API-guide → Opret en historie.

Gør krav på den. En agent tilføjer sig selv som ejer ved at poste 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 kalderen, så agenten behøver ikke kende sit eget id. Boardet viser nu agenten som ejer, og det er sådan et menneske, der ser med, ved, at arbejdet er taget.

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

Derefter går agenten hen og gør arbejdet — læser repoet, skriver koden, åbner pull requesten. Den del sker i dit udviklingsværktøj, ikke her.

Vedhæft 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 genkendes som sådan — du behøver ikke sige det. Historien og den kode, der lukker den, ligger nu ét klik fra hinanden, i begge retninger.

Afslut den. Skift til finished og stop dér. En feature har stadig delivered og accepted foran sig, og det er gennemgangsportene: en anden end agenten afgør, at arbejdet er rigtigt. En chore har ingen sådan port — started → accepted er hele dens resterende vej.

En importeret lukket issue, hvis CODE-sektion linker til den pull request, der rettede den, med GitHub-kommentarerne ved siden af

Tokens og hastighedsgrænser

Enhver import autentificerer sig. Hentningen af issues, kommentarer og pull requests kører på GitHubs GraphQL-API, og GraphQL afviser en forespørgsel uden token — der er ingen anonym niveau, hverken på et offentligt repository eller et privat. Spørgsmålet er aldrig, om et token går til GitHub, kun hvis.

Dit eget token

Send token på importkaldet, eller --token til GitHub-to-EAT. Et finkornet personligt adgangstoken med læseadgang til repositoriets issues er nok. Det driver de opstrøms GitHub-kald og intet andet: det logges aldrig, revisionslogges aldrig, gemmes aldrig og ekkoes aldrig tilbage i et svar eller en fejl.

Tag dit eget med til alt ud over en demo. Så bruger du et budget, ingen anden rører, og ingen forkontrol kan afvise dig på grund af en andens import.

--engine direct lader dig ikke vælge. Den motor læser GitHub fra din maskin frem for gennem Trackeren, så serverens token er uden for rækkevidde; en kørsel uden token afslutter med 2 og en brugsfejl, før den henter eller skriver noget. GITHUB_TOKEN i dit miljø eller din .env tæller på samme måde som --token.

Det er gennemgangen af issues, der kræver tokenet, ikke hele motoren. direct læser issues, kommentarer og pull requests over GraphQL, som ikke har nogen anonym tilstand; den rører kun REST for release-listen og den gratis /rate_limit-sondering. Værktøjet leverer stadig en ældre anonym REST-henter, der kunne køre en import af et offentligt repository inden for budgettet på 60 i timen, men ingen CLI-sti når den længere, og den skal slettes — betragt derfor --token som påkrævet for direct.

Deploymentets delte token

Send intet token, og serveren indsætter det platform-token, dens operatør har konfigureret (GITHUB_IMPORT_PAT). Tre grænser følger med:

Det er valgfri konfiguration. Den hostede eastagiletracker.com stiller et til rådighed, så en import af et offentligt repository uden token virker der. En selvhostet installation — den downloadede binærfil — har ingen, før dens operatør sætter GITHUB_IMPORT_PAT i miljøet, og indtil da afviser den enhver import uden token med 400 import_github_no_token.
Det læser kun offentlige repositories. Den hostede tjeneste udsteder det skrivebeskyttet over offentlige repos, så et privat repository kræver altid dit eget token.
Alle kaldere på deploymentet deler ét budget. Før en import uden token kører, læser serveren det delte tokens resterende GraphQL-point og afviser med 400 import_github_shared_quota_low under 500. Et budget, der løber tør midt i importen, får jobbet til at fejle med import_github_rate_limited_platform. Begge beskeder nævner samme udbedring: stil dit eget token til rådighed.

Hvad token giver dig

GitHub måler sine to API’er hver for sig, og det uautentificerede loft ligger to størrelsesordener lavere.

GitHub-API	Bruges til	Med token	Uden token
GraphQL	Issues, kommentarer, pull requests, under-issues, afhængigheder	5.000 point i timen, målt på de knuder en forespørgsel returnerer	Afvist — GraphQL har intet uautentificeret niveau
REST	Releases (`include_releases`) og `/rate_limit`-forkontrollen	5.000 forespørgsler i timen	60 forespørgsler i timen, talt pr. IP-adresse og delt med alle bag den

En import falder aldrig tilbage til det niveau på 60 i timen: uden et token at sende afvises forespørgslen på forhånd frem for at blive prøvet igen anonymt. Tallet betyder noget for det, du gør rundt om importen — et script, der læser GitHub direkte, eller en shell på samme net som andre klienter, bruger 60 forespørgsler på sekunder.

Læs dit resterende budget når som helst; GET /rate_limit er undtaget fra begge grænser, så kontrollen koster ingenting:

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

GraphQL-point er ikke forespørgsler. GitHub måler en forespørgsel på de knuder, den returnerer, så én side med 100 issues plus deres kommentarer og tilknyttede personer koster mange point, og et stort repository bruger timebudgettet på langt færre kald, end tallene fra REST-tiden antyder. --dry-run (trin 3) og dry_run (trin 4) koster hver de samme point som den rigtige hentning — det er dét, der gør deres tal troværdige — så regn med to gennemløb, når du forbereder en stor import.

Hvor du går hen nu

API-guide — søgegrammatikken, hændelsesstrømmen, masseovergange, idempotente skrivninger og resten af fladen.
Betjeningsvejledning — de samme handlinger fra brugerfladen, og de ti andre importører.
Introduktion — hvorfor tilstandsmaskinen og de fire historietyper har denne form.
GitHub-to-EAT — importørens eget repository: hvert flag, begge motorer, og hvordan du bidrager til det.