Naplnění projektu z GitHub repozitáře

Nasměrujte agenta na GitHub repozitář a dostanete zpět funkční board: každou issue jako story, ve stavu, který odpovídá její historii, s přenesenými checklisty, štítky a milníky. Pak tentýž agent story zvedne, převezme ji, protáhne ji stavovým automatem a připojí pull request, který otevřel.

Tato stránka popisuje celou tu smyčku. Krok naplnění má dvě cesty: GitHub-to-EAT, otevřený importér od East Agile, ho zvládne jedním příkazem (krok 3); import API dělá tutéž práci volání po volání (kroky 4 a 5), a právě to řídí agent, když chce handle úlohy. Všechno další běží na API, protože smyslem je, aby zbytek zvládl agent bez dozoru.

Tohle není zvláštní „AI import”. Krok naplnění je tentýž GitHub importér, který spustíte ručně z Nastavení projektu → Import / Export, popsaný v Provozní pokyny → Import z jiných trackerů. Agent volá stejný endpoint jako vy. Co tato stránka přidává, je všechno okolo: kdo drží klíč, jak import zkontrolovat, než začne zapisovat, a co agent s boardem dělá, jakmile existuje.

Co potřebujete

• Projekt — a relaci nebo klíč ea_user_…, kterým ho založíte.
• Agentský klíč — klíč ea_agent_… omezený na ten projekt. Jakou roli potřebuje, závisí na tom, kolik ze smyčky má agent zvládnout sám; viz krok 2. Viz také Průvodce API → Dva druhy klíčů.
• Osobní přístupový token GitHubu — s právem číst issues repozitáře. Každý import se autentizuje, protože načítání běží přes GraphQL API GitHubu a GraphQL odmítne požadavek bez tokenu. Vynechat ho můžete jen tehdy, když načítá Tracker za vás: veřejný repozitář, na instalaci, která má sdílený záložní token (hostovaná eastagiletracker.com jeden má; vlastní instalace žádný nemá, dokud její provozovatel nenastaví GITHUB_IMPORT_PAT), a nikdy s --engine direct nástroje GitHub-to-EAT. Viz Tokeny a limity požadavků.
• Node.js 22+ — jen pro cestu přes GitHub-to-EAT v kroku 3. Cesta přes API si vystačí s curl.

1. Založte projekt

Projekt musí existovat dřív než agentský klíč a musí ho založit člověk: agentské klíče se při vydání vážou na jediný projekt a samy projekt založit nedokážou. Vytvořte ho v rozhraní, nebo vlastním klíčem 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}'

Odpověď nese project_id, které potřebuje každé volání níže.

2. Vydejte agentský klíč

Vlastník projektu vytváří agentské klíče v Nastavení projektu → Agenti. Zvolená role rozhoduje, kolik z této stránky zvládne agent sám, a existují dvě rozumné odpovědi:

• owner — jediný klíč projde celou smyčku, včetně importu. Importovat smí jen vlastník, protože import přepisuje tvar projektu jako celek. Vydat agenta s rolí owner vyžaduje, abyste sami byli vlastníkem projektu: role agenta nikdy nemůže překročit roli jeho tvůrce.
• member — nejnižší oprávnění. Agent přebírá stories, posouvá je, komentuje a připojuje pull requesty, ale importovat nemůže. Import spustíte sami (krok 5) vlastním klíčem a board pak předáte agentovi.

Tak či tak nenechávejte výchozí hodnotu. Nový agentský klíč je viewer, dokud neřeknete jinak, a viewer si board přečte, ale story nepřevezme ani neposune — a to je většina této smyčky.

Agentské klíče tu hrají roli i mimo přístup. Agentský klíč vystupuje jako pojmenovaný účastník v jediném projektu, takže každá story, kterou vytvoří, každá změna stavu, kterou provede, i každý komentář, který napíše, je v historii připsán tomu agentovi — odlišitelně od vaší vlastní práce, ne s ní smíchaně.

export TRACKER_TOKEN="ea_agent_xxxxx"

Nechte agenta přečíst /meta dřív než cokoli jiného:

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

To zodpoví dvě otázky, které by agent jinak jen odhadoval: k jakému projektu je klíč vázán (auth.project_id) a které změny stavu jsou pro který typ story legální (transitions). Feature běží unstarted → started → finished → delivered → accepted; chore je jen unstarted → started → accepted. Přečíst mapu je lepší než ji natvrdo zapsat.

3. Import přes GitHub-to-EAT

GitHub-to-EAT je vlastní otevřený importér East Agile: nástroj příkazové řádky pod licencí MIT, který zvládne celý krok naplnění — kroky 4 a 5 níže — jediným příkazem. Sáhněte po něm, když u terminálu sedí člověk. Sáhněte po API pod ním, když řídí agent bez dozoru a chce handle úlohy, na který se ptát.

Vyžaduje Node.js 22+ a nemá žádné vlastní běhové závislosti. Zatím není publikován na npm, takže ho nainstalujte z repozitáře:

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

Pak ho nasměrujte na klíč z kroku 2 a projekt z kroku 1:

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

Nejprve vypíše legendu mapování — přesně jak každý zvolený typ dopadne — a než cokoli zapíše, požádá o potvrzení. Mimo terminál, v rouře, v CI nebo v agentovi není kam ten dotaz zobrazit, takže běh, který by zapisoval, musí předat --yes; bez toho nástroj skončí s 2 a nezapíše nic, místo aby vaši odpověď odhadl. Opakované spuštění je bezpečné: co už bylo naimportováno, se přeskočí, nikdy nezduplikuje.

Přepínač	Co dělá
--dry-run	Předběžná kontrola, pak výpis plánu, který by provedl — kolik stories by naimportoval, kolik by jich přeskočil jako už existující — a nezapíše nic. Nepotřebuje --yes.
--include	Které typy importovat, oddělené čárkami: issues,prs,milestones,releases,deps. Výchozí je issues a každý výběr ho musí obsahovat. Jsou to tytéž volby jako v tabulce v kroku 6.
--token	Váš osobní přístupový token GitHubu (počítá se i GITHUB_TOKEN v prostředí nebo v .env). Potřebuje repo, nebo jemné právo Issues: Read, na daném repozitáři. Povinný pro soukromý repozitář, pro server bez sdíleného záložního tokenu a vždy pro --engine direct. Vynechte ho na výchozím enginu hostované služby a Tracker utratí vlastní sdílený rozpočet — viz Tokeny a limity požadavků.
--engine	server, výchozí volba, pošle jediné volání /import/json a nechá načítání, mapování i zápis na Trackeru. direct spustí tutéž pipeline na vašem stroji a zapisuje přes veřejné API — čte tedy GitHub sám a vždy potřebuje token, jinak končí s 2.
--states, --milestones, --story-type, --no-comments, --no-tasks	Zúží nebo přepíší mapování pro jeden běh; nic se neuchovává. Každý z nich implikuje --engine direct.

Nastavte EAT_API_BASE a EAT_APP_BASE, chcete-li mířit na vlastní nebo lokální Tracker; obojí míří ve výchozím stavu na hostovanou službu. README nese úplný přehled přepínačů, návratové kódy a řešení potíží.

Všechno níže je tentýž import řízený volání po volání, což je to, co chcete, když ho spouští agent.

4. Nejdřív běh nanečisto

Import je jen pro vlastníka — použijte agentský klíč s rolí owner, nebo vlastní klíč, pokud jste agenta nechali jako member. Spusťte ho nejdřív s dry_run, než mu dovolíte zapisovat:

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

Běh nanečisto načte z GitHubu, přeloží a odstraní duplicity přesně jako ten skutečný, ohlásí tytéž počty — imported, skipped, errors, unmatched — a pak celou transakci vrátí zpět. Nic nezůstane a do auditního logu se nedostane žádná událost o dokončeném importu. Je to nejlevnější způsob, jak zjistit, že jste chtěli zahrnout milníky, nebo že je repozitář větší, než jste čekali — dokud vás to ještě nic nestojí.

Každé volání /import/json je asynchronní, běh nanečisto nevyjímaje: endpoint vrací 202 s handle úlohy, ne výsledek, a počty dorazí na úlohu, až se na ni doptáte (krok 5). Úloha běhu nanečisto dojde do stavu done stejně jako ta skutečná; rozdíl je v tom, že se nic nezapsalo.

5. Spusťte import

Vypusťte dry_run a pošlete znovu. Endpoint jako předtím vrací 202 s handle úlohy:

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

Ptejte se na úlohu, dokud nedosáhne koncového stavu:

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

Stav běží pending → fetching → writing → done | failed. Koncové jsou jen poslední dva: done nese výsledné počty, failed nese chybovou zprávu a stabilní strojový kód, podle kterého se dá větvit. Zatímco načítání stránkuje, progress_current a progress_total říkají, na které stránce je — stojí za to je zobrazit, když se dívá člověk.

Tokeny. Předejte "token": "github_pat_…". Vynechte ho a server dosadí sdílený platformový token, který čte pouze veřejné repozitáře a účtuje se všem volajícím na instalaci — Tokeny a limity požadavků popisuje, co vás to stojí. Ať běží kterýkoli token, řídí upstream volání GitHubu a nic jiného: nikdy se neloguje, nikdy nejde do auditního logu, nikdy se neukládá a nikdy se nevrací v odpovědi ani v chybě.

Opakované spuštění je bezpečné. Řádek, který už byl naimportován, se pozná podle id ve zdroji a přeskočí se, nezduplikuje. Druhý import doplní board o to, co přibylo od prvního.

6. Co přistane na boardu

Issues se importují ve výchozím stavu. Všechno ostatní je volitelné, jeden přepínač na typ:

Z GitHubu	Se stane	Přepínač
Issue	Story. Otevřená → unstarted v Backlogu. Zavřená → accepted, nebo rejected, když GitHub uvádí, že issue byla zavřena jako not_planned nebo duplicate (story pak nese odpovídající štítek).	výchozí
Checklist v těle issue	Úkoly — každý řádek - [ ] / - [x] se stane jedním úkolem v pořadí podle textu, [x] přichází hotový. Checklist zůstává i v popisu.	výchozí
Štítky	Štítky, přenesené beze změny.	výchozí
Pull request	Story se štítkem pull-request. Otevřený → started, zmergovaný → accepted, zavřený bez mergu → rejected.	include_pull_requests
Milník	Epika pojmenovaná podle milníku a odduplikovaná podle názvu — dvě issues sdílející milník skončí v jedné epice. S vypnutým přepínačem jede místo toho jako štítek milestone:<název>.	include_milestones
Release	Release story. Publikovaná → accepted, koncept → unstarted.	include_releases
Závislost issue	Blocker na story. Jen issues, nikdy pull requesty.	include_dependencies

Typ story se odvodí, když ho issue neuvádí. Štítek obsahující bug, fix nebo defect — nebo název začínající na fix či bug — z ní udělá bug; chore, maintenance, devops nebo infra z ní udělají chore; cokoli jiného je feature. Vyplatí se to vědět před importem, protože v East Agile Trackeru nesou pointy jen features a jen features sytí velocity. Viz Úvod → Stories.

7. Agent pracuje na story

Board už má historii a agent má klíč. Smyčka odtud dál jsou čtyři volání.

Najděte story, nebo napište novou. Profiltrujte board a hledejte, co zvednout:

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

import_source=github zúží výběr na to, co přinesl import. Pokud agent našel práci, kterou repozitář nikdy nezachytil, vytvoří story sám — viz Průvodce API → Vytvoření story.

Převezměte ji. Agent se přidá jako vlastník odesláním prázdného těla:

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

Prázdné tělo znamená volající, takže agent nemusí znát vlastní id. Board teď ukazuje agenta jako vlastníka, a podle toho člověk, který se dívá, pozná, že je práce zabraná.

Rozjeďte ji.

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

Pak agent jde a odvede práci — přečte repozitář, napíše kód, otevře pull request. Tahle část se odehrává ve vašem vývojovém nástroji, ne tady.

Připojte 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"}'

URL pull requestu na GitHubu se rozpozná sama — nemusíte to říkat. Story a kód, který ji uzavírá, jsou teď v obou směrech na jedno kliknutí.

Dokončete ji. Přejděte na finished a tam skončete. Feature má před sebou ještě delivered a accepted, a to jsou kontrolní body: že je práce v pořádku, rozhodne někdo jiný než agent. Chore takový kontrolní bod nemá — started → accepted je celá její zbývající cesta.

Tokeny a limity požadavků

Každý import se autentizuje. Načítání issues, komentářů a pull requestů běží přes GraphQL API GitHubu a GraphQL odmítne požadavek bez tokenu — anonymní úroveň neexistuje, ani u veřejného repozitáře, ani u soukromého. Otázka nikdy nezní, zda na GitHub dorazí token, jen čí.

Váš vlastní token

Předejte token při volání importu, nebo --token nástroji GitHub-to-EAT. Stačí jemně odstupňovaný osobní přístupový token s právem číst issues repozitáře. Řídí upstream volání GitHubu a nic jiného: nikdy se neloguje, nikdy nejde do auditního logu, nikdy se neukládá a nikdy se nevrací v odpovědi ani v chybě.

Na cokoli za hranicí ukázky si přineste vlastní. Utrácíte pak rozpočet, na který nikdo jiný nesahá, a žádná předběžná kontrola vás nemůže odmítnout kvůli cizímu importu.

--engine direct vám na výběr nedává. Ten engine čte GitHub z vašeho stroje, ne přes Tracker, takže token serveru je mimo dosah; běh bez tokenu skončí s 2 a chybou použití dřív, než cokoli načte nebo zapíše. GITHUB_TOKEN ve vašem prostředí nebo v .env se počítá stejně jako --token.

Token si vynucuje průchod issues, ne celý engine. direct čte issues, komentáře a pull requesty přes GraphQL, který nemá anonymní režim; REST se dotkne jen kvůli výpisu releases a bezplatné sondě /rate_limit. Nástroj stále obsahuje starší anonymní REST fetcher, který zvládl import veřejného repozitáře v rámci limitu 60 za hodinu, ale žádná cesta v CLI se k němu už nedostane a je určen ke smazání — --token proto považujte pro direct za povinný.

Sdílený token instalace

Nepošlete žádný token a server dosadí platformový token, který nastavil jeho provozovatel (GITHUB_IMPORT_PAT). Nesou se s ním tři omezení:

• Je to volitelná konfigurace. Hostovaná eastagiletracker.com jeden poskytuje, takže import veřejného repozitáře bez tokenu tam funguje. Vlastní instalace — stažená binárka — žádný nemá, dokud její provozovatel nenastaví v prostředí GITHUB_IMPORT_PAT, a do té doby odmítne každý import bez tokenu s 400 import_github_no_token.
• Čte pouze veřejné repozitáře. Hostovaná služba ho vydává jen ke čtení nad veřejnými repozitáři, takže soukromý repozitář vždy potřebuje váš vlastní token.
• Všichni volající na instalaci sdílejí jediný rozpočet. Než import bez tokenu poběží, server přečte zbývající GraphQL body sdíleného tokenu a pod hranicí 500 odmítne s 400 import_github_shared_quota_low. Rozpočet, který dojde uprostřed importu, nechá úlohu selhat s import_github_rate_limited_platform. Obě hlášky uvádějí tutéž nápravu: dodejte vlastní token.

Co token přináší

GitHub měří obě svá API zvlášť a neautentizovaný strop je o dva řády níž.

API GitHubu	Slouží k	S tokenem	Bez tokenu
GraphQL	Issues, komentáře, pull requesty, pod-issues, závislosti	5 000 bodů za hodinu, počítaných podle uzlů, které dotaz vrátí	Odmítnuto — GraphQL nemá anonymní úroveň
REST	Releasy (include_releases) a předběžná kontrola /rate_limit	5 000 požadavků za hodinu	60 požadavků za hodinu, počítaných na IP adresu a sdílených se všemi za ní

Import na tu úroveň 60 za hodinu nikdy nespadne: bez tokenu k odeslání je požadavek odmítnut dopředu, místo aby se opakoval anonymně. To číslo je důležité pro to, co děláte okolo importu — skript, který čte GitHub přímo, nebo shell ve stejné síti jako další klienti, vyčerpá 60 požadavků během vteřin.

Zbývající rozpočet si přečtěte kdykoli; GET /rate_limit je z obou limitů vyňatý, takže kontrola nic nestojí:

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

GraphQL body nejsou požadavky. GitHub oceňuje dotaz podle uzlů, které vrátí, takže jedna stránka se 100 issues i s komentáři a přiřazenými lidmi stojí mnoho bodů a velký repozitář utratí hodinový rozpočet v mnohem méně voláních, než čísla z éry REST napovídají. --dry-run (krok 3) i dry_run (krok 4) stojí každý tolik bodů co skutečné načtení — právě proto jsou jejich počty důvěryhodné — takže u velkého importu počítejte se dvěma průchody.

Kam dál

• Průvodce API — gramatika vyhledávání, proud událostí, hromadné přechody, idempotentní zápisy a zbytek plochy.
• Provozní pokyny — tytéž operace z rozhraní a dalších deset importérů.
• Úvod — proč mají stavový automat a čtyři typy story právě tenhle tvar.
• GitHub-to-EAT — vlastní repozitář importéru: každý přepínač, oba enginy a jak do něj přispět.