Ein Projekt aus einem GitHub-Repo befüllen

Richten Sie einen Agenten auf ein GitHub-Repository und Sie bekommen ein arbeitsfähiges Board zurück: jedes Issue als Story, in dem Zustand, den seine Historie vorgibt, mit Checklisten, Labels und Meilensteinen übernommen. Danach greift derselbe Agent eine Story auf, beansprucht sie, bewegt sie durch die Zustandsmaschine und verknüpft den Pull Request, den er geöffnet hat.

Diese Seite beschreibt diese Schleife von Anfang bis Ende. Der Befüllungsschritt hat zwei Wege: GitHub-to-EAT, East Agiles quelloffener Importer, erledigt ihn mit einem einzigen Befehl (Schritt 3); die Import-API erledigt dieselbe Arbeit Aufruf für Aufruf (Schritte 4 und 5), und genau das steuert ein Agent, wenn er das Job-Handle haben will. Alles danach läuft über die API, denn der Sinn der Sache ist, dass ein Agent den Rest unbeaufsichtigt erledigen kann.

Das ist kein separater „KI-Import”. Der Befüllungsschritt ist derselbe GitHub-Importer, den Sie unter Projekteinstellungen → Import / Export von Hand ausführen können, beschrieben in Bedienungsanleitung → Aus anderen Trackern importieren. Der Agent ruft denselben Endpunkt auf wie Sie. Was diese Seite hinzufügt, ist alles drumherum: wer den Schlüssel hält, wie Sie den Import prüfen, bevor er schreibt, und was der Agent mit dem Board anfängt, sobald es existiert.

Die GitHub-Quelle im Tab Import / Export: Owner und Repository ausgefüllt, Token leer, Pull Requests und Meilensteine angehakt

Was Sie brauchen

Ein Projekt — und eine Sitzung oder einen ea_user_…-Schlüssel, um es anzulegen.
Einen Agenten-Schlüssel — einen ea_agent_…-Schlüssel, der auf dieses Projekt beschränkt ist. Welche Rolle er braucht, hängt davon ab, wie viel von der Schleife der Agent laufen soll; siehe Schritt 2. Siehe auch API-Leitfaden → Zwei Arten von Schlüsseln.
Ein GitHub Personal Access Token — mit Lesezugriff auf die Issues des Repositories. Jeder Import authentifiziert sich, weil der Abruf über GitHubs GraphQL-API läuft und GraphQL eine Anfrage ohne Token ablehnt. Weglassen können Sie es nur, wenn der Tracker in Ihrem Namen abruft: ein öffentliches Repository, auf einem Deployment, das ein geteiltes Ausweich-Token hat (das gehostete eastagiletracker.com hat eines; eine selbst gehostete Installation hat keines, bis ihr Betreiber GITHUB_IMPORT_PAT setzt), und nicht mit GitHub-to-EATs --engine direct. Siehe Token und Ratenlimits.
Node.js 22+ — nur für den GitHub-to-EAT-Weg in Schritt 3. Der API-Weg braucht nichts außer curl.

1. Das Projekt anlegen

Das Projekt muss vor dem Agenten-Schlüssel existieren, und es muss von einem Menschen angelegt werden: Agenten-Schlüssel sind beim Ausstellen an ein Projekt gebunden und können keine Projekte anlegen. Legen Sie es in der Oberfläche an oder mit Ihrem eigenen ea_user_…-Schlüssel:

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

Die Antwort trägt die project_id, die jeder Aufruf weiter unten braucht.

2. Einen Agenten-Schlüssel ausstellen

Ein Projekteigentümer legt Agenten-Schlüssel unter Projekteinstellungen → Agenten an. Die gewählte Rolle entscheidet, wie viel von dieser Seite der Agent allein erledigen kann, und dafür gibt es zwei sinnvolle Antworten:

owner — ein Schlüssel läuft die ganze Schleife, Import eingeschlossen. Importieren ist nur dem Eigentümer erlaubt, weil ein Import die Form eines Projekts im Ganzen umschreibt. Einen Agenten mit der Rolle owner auszustellen setzt voraus, dass Sie selbst Projekteigentümer sind: Die Rolle eines Agenten kann die seines Erstellers nie übersteigen.
member — geringstes Privileg. Der Agent beansprucht Storys, bewegt sie, kommentiert und verknüpft Pull Requests, kann aber nicht importieren. Den Import führen Sie selbst aus (Schritt 5), mit Ihrem eigenen Schlüssel, und übergeben das Board danach an den Agenten.

So oder so: Lassen Sie es nicht beim Standard. Ein neuer Agenten-Schlüssel ist viewer, solange Sie nichts anderes sagen, und ein Viewer kann das Board lesen, aber keine Story beanspruchen oder bewegen — und das ist der Großteil dieser Schleife.

Agenten-Schlüssel zählen hier aus einem Grund, der über den Zugriff hinausgeht. Ein Agenten-Schlüssel handelt als benannter Teilnehmer in genau einem Projekt, also wird jede Story, die er anlegt, jeder Zustandswechsel, den er vornimmt, und jeder Kommentar, den er schreibt, in der Historie diesem Agenten zugeschrieben — unterscheidbar von Ihrer eigenen Arbeit statt mit ihr verschmolzen.

export TRACKER_TOKEN="ea_agent_xxxxx"

Lassen Sie den Agenten vor allem anderen /meta lesen:

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

Das beantwortet die zwei Fragen, die der Agent sonst raten müsste: an welches Projekt der Schlüssel gebunden ist (auth.project_id) und welche Zustandswechsel für welchen Story-Typ zulässig sind (transitions). Eine Feature läuft unstarted → started → finished → delivered → accepted; eine Chore nur unstarted → started → accepted. Die Karte zu lesen schlägt es, sie fest zu verdrahten.

3. Mit GitHub-to-EAT importieren

GitHub-to-EAT ist East Agiles eigener quelloffener Importer: ein MIT-lizenziertes Kommandozeilenwerkzeug, das den gesamten Befüllungsschritt — die Schritte 4 und 5 unten — mit einem Befehl erledigt. Greifen Sie dazu, wenn ein Mensch am Terminal sitzt. Greifen Sie zur API darunter, wenn ein Agent unbeaufsichtigt arbeitet und das Job-Handle zum Abfragen braucht.

Es braucht Node.js 22+ und hat keine eigenen Laufzeitabhängigkeiten. Es ist noch nicht auf npm veröffentlicht, installieren Sie es also aus dem Repository:

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

Richten Sie es dann auf den Schlüssel aus Schritt 2 und das Projekt aus Schritt 1:

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

Es druckt zuerst eine Zuordnungslegende — genau, wie jeder gewählte Typ landen wird — und fragt nach einer Bestätigung, bevor es irgendetwas schreibt. Außerhalb eines Terminals, in einer Pipe, in CI oder in einem Agenten gibt es keinen Ort für diese Rückfrage, also muss ein Lauf, der schreiben würde, --yes übergeben; ohne das beendet sich das Werkzeug mit 2 und schreibt nichts, statt Ihre Antwort zu raten. Erneutes Ausführen ist sicher: Was bereits importiert wurde, wird übersprungen, nie dupliziert.

Flag	Was es tut
`--dry-run`	Vorabprüfung, dann Ausgabe des Plans, den es ausführen würde — wie viele Storys es importieren, wie viele es als bereits vorhanden überspringen würde — und schreibt nichts. Braucht kein `--yes`.
`--include`	Welche Typen importiert werden, kommagetrennt: `issues,prs,milestones,releases,deps`. Standard ist `issues`, und jede Auswahl muss es enthalten. Das sind dieselben Opt-ins wie in der Tabelle in Schritt 6.
`--token`	Ihr GitHub Personal Access Token (`GITHUB_TOKEN` in der Umgebung oder in einer `.env` zählt ebenso). Es braucht `repo` oder feingranular Issues: Read auf diesem Repository. Erforderlich für ein privates Repository, für einen Server ohne geteiltes Ausweich-Token und immer für `--engine direct`. Lassen Sie es auf der Standard-Engine des gehosteten Dienstes weg, gibt der Tracker sein eigenes geteiltes Budget aus — siehe Token und Ratenlimits.
`--engine`	`server`, der Standard, sendet einen `/import/json`-Aufruf und lässt den Tracker abrufen, zuordnen und schreiben. `direct` führt dieselbe Pipeline auf Ihrem Rechner aus und schreibt stattdessen über die öffentliche API — es liest GitHub also selbst und braucht immer ein Token, sonst beendet es sich mit `2`.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Schränken die Zuordnung für einen Lauf ein oder überschreiben sie; nichts davon wird persistiert. Jedes davon impliziert `--engine direct`.

Setzen Sie EAT_API_BASE und EAT_APP_BASE, um es auf einen selbst gehosteten oder lokalen Tracker zu richten; beide zeigen standardmäßig auf den gehosteten Dienst. Die README trägt die vollständige Flag-Referenz, die Exit-Codes und die Fehlersuche.

Alles darunter ist derselbe Import, Aufruf für Aufruf gesteuert — und das wollen Sie, wenn ein Agent ihn ausführt.

4. Erst ein Trockenlauf

Importieren ist nur dem Eigentümer erlaubt — nutzen Sie einen Agenten-Schlüssel mit der Rolle owner oder Ihren eigenen Schlüssel, falls Sie den Agenten auf member gelassen haben. Führen Sie ihn zuerst mit dry_run aus, bevor Sie ihn schreiben lassen:

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

Ein Trockenlauf ruft von GitHub ab, löst auf und dedupliziert genau wie der echte Lauf, meldet dieselben Zahlen — imported, skipped, errors, unmatched — und rollt danach die ganze Transaktion zurück. Nichts bleibt bestehen, und kein Ereignis über einen abgeschlossenen Import erreicht Ihr Audit-Log. Das ist der billigste Weg, herauszufinden, dass Sie Meilensteine einschließen wollten oder dass ein Repo größer ist als gedacht — solange es Sie noch nichts kostet.

Jeder Aufruf von /import/json ist asynchron, der Trockenlauf eingeschlossen: Der Endpunkt liefert 202 mit einem Job-Handle zurück, kein Ergebnis, und die Zahlen kommen auf dem Job an, wenn Sie ihn abfragen (Schritt 5). Der Job eines Trockenlaufs erreicht done wie ein echter; der Unterschied ist, dass nichts geschrieben wurde.

5. Den Import ausführen

Lassen Sie dry_run weg und senden Sie erneut. Wie zuvor liefert der Endpunkt 202 mit einem Job-Handle zurück:

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

Fragen Sie den Job ab, bis er einen Endzustand erreicht:

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

Der Status läuft pending → fetching → writing → done | failed. Nur die letzten beiden sind Endzustände: done trägt die Ergebniszahlen, failed trägt eine Fehlermeldung und einen stabilen Maschinencode, auf den Sie verzweigen können. Während der Abruf paginiert, sagen progress_current und progress_total, auf welcher Seite er ist — es lohnt sich, das anzuzeigen, wenn ein Mensch zusieht.

Token. Übergeben Sie "token": "github_pat_…". Lassen Sie es weg, setzt der Server das geteilte Plattform-Token ein, das nur öffentliche Repositories liest und über alle Aufrufer des Deployments abgerechnet wird — Token und Ratenlimits beschreibt, was Sie das kostet. Welches Token auch verwendet wird: Es treibt die vorgelagerten GitHub-Aufrufe an und sonst nichts. Es wird nie protokolliert, nie im Audit-Log erfasst, nie gespeichert und nie in einer Antwort oder einem Fehler zurückgegeben.

Erneutes Ausführen ist sicher. Eine bereits importierte Zeile wird über ihre Quell-ID erkannt und übersprungen, nicht dupliziert. Ein zweiter Import füllt das Board mit dem auf, was seit dem ersten dazugekommen ist.

6. Was auf dem Board landet

Issues werden standardmäßig importiert. Alles andere ist Opt-in, ein Flag je Typ:

Von GitHub	Wird zu	Flag
Issue	Eine Story. Offen → unstarted im Backlog. Geschlossen → accepted, oder rejected, wenn GitHub sagt, das Issue wurde als `not_planned` oder `duplicate` geschlossen (die Story trägt dann ein passendes Label).	Standard
Checkliste im Issue-Text	Tasks — jede Zeile `- [ ]` / `- [x]` wird in der Reihenfolge des Textes zu einer Task, `[x]` kommt bereits erledigt an. Die Checkliste bleibt zusätzlich in der Beschreibung.	Standard
Labels	Labels, unverändert übernommen.	Standard
Pull Request	Eine Story mit dem Label `pull-request`. Offen → started, gemerged → accepted, ungemerged geschlossen → rejected.	`include_pull_requests`
Meilenstein	Ein Epic, benannt nach dem Meilenstein, per Titel dedupliziert — zwei Issues mit demselben Meilenstein landen in einem Epic. Ist das Flag aus, reist er stattdessen als Label `milestone:<Titel>` mit.	`include_milestones`
Release	Eine Release-Story. Veröffentlicht → accepted, Entwurf → unstarted.	`include_releases`
Issue-Abhängigkeit	Ein Blocker an der Story. Nur Issues, nie Pull Requests.	`include_dependencies`

Der Story-Typ wird abgeleitet, wenn das Issue ihn nicht nennt. Ein Label, das bug, fix oder defect enthält — oder ein Titel, der mit fix oder bug beginnt — macht daraus einen Bug; chore, maintenance, devops oder infra macht daraus eine Chore; alles andere ist eine Feature. Das ist vor dem Import wissenswert, denn in East Agile Tracker tragen nur Features Points und nur Features speisen die Velocity. Siehe Einführung → Storys.

Ein Projekt-Board direkt nach dem Import des Beispiel-Repositorys: Issues als Stories mit ihren Labels, Meilensteine als Epics und GitHub-Personen als Owner

7. Der Agent bearbeitet eine Story

Jetzt hat das Board Historie, und der Agent hat einen Schlüssel. Die Schleife besteht ab hier aus vier Aufrufen.

Eine Story finden oder eine schreiben. Filtern Sie das Board nach etwas, das aufzugreifen ist:

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

import_source=github schränkt es auf das ein, was der Import mitgebracht hat. Hat der Agent Arbeit gefunden, die das Repo nie erfasst hat, legt er stattdessen die Story an — siehe API-Leitfaden → Eine Story anlegen.

Sie beanspruchen. Ein Agent trägt sich als Eigentümer ein, indem er einen leeren Body postet:

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

Ein leerer Body bedeutet der Aufrufer, der Agent muss seine eigene ID also nicht kennen. Das Board zeigt den Agenten jetzt als Eigentümer, und daran erkennt ein zuschauender Mensch, dass die Arbeit vergeben ist.

Sie starten.

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

Dann geht der Agent hin und macht die Arbeit — liest das Repo, schreibt den Code, öffnet den Pull Request. Dieser Teil passiert in Ihrem Entwicklungswerkzeug, nicht hier.

Den Pull Request anhängen.

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

Eine GitHub-Pull-Request-URL wird als solche erkannt — Sie müssen es nicht dazusagen. Die Story und der Code, der sie schließt, sind jetzt in beide Richtungen einen Klick voneinander entfernt.

Sie abschließen. Wechseln Sie auf finished und hören Sie dort auf. Vor einer Feature liegen noch delivered und accepted, und das sind die Prüfschritte: Jemand anderes als der Agent entscheidet, dass die Arbeit stimmt. Eine Chore hat diesen Prüfschritt nicht — started → accepted ist ihr ganzer restlicher Weg.

Ein importiertes geschlossenes Issue, dessen Abschnitt CODE den behebenden Pull Request verlinkt, daneben die GitHub-Kommentare

Token und Ratenlimits

Jeder Import authentifiziert sich. Der Abruf von Issues, Kommentaren und Pull Requests läuft über GitHubs GraphQL-API, und GraphQL lehnt eine Anfrage ohne Token ab — es gibt keine anonyme Stufe, weder bei einem öffentlichen noch bei einem privaten Repository. Die Frage ist nie, ob ein Token zu GitHub geht, sondern nur wessen.

Ihr eigenes Token

Übergeben Sie token beim Import-Aufruf oder --token an GitHub-to-EAT. Ein feingranulares Personal Access Token mit Lesezugriff auf die Issues des Repositories genügt. Es treibt die vorgelagerten GitHub-Aufrufe an und sonst nichts: Es wird nie protokolliert, nie im Audit-Log erfasst, nie gespeichert und nie in einer Antwort oder einem Fehler zurückgegeben.

Bringen Sie für alles jenseits einer Demo Ihr eigenes mit. Dann geben Sie ein Budget aus, das niemand sonst anfasst, und keine Vorabprüfung kann Sie wegen des Imports eines anderen abweisen.

--engine direct lässt Ihnen keine Wahl. Diese Engine liest GitHub von Ihrem Rechner aus statt über den Tracker, das Server-Token ist damit außer Reichweite; ein Lauf ohne Token endet mit 2 und einem Nutzungsfehler, bevor er abruft oder schreibt. GITHUB_TOKEN in Ihrer Umgebung oder Ihrer .env zählt genauso wie --token.

Das Token erzwingt der Issue-Durchlauf, nicht die ganze Engine. direct liest Issues, Kommentare und Pull Requests über GraphQL, das keinen anonymen Modus hat; REST berührt sie nur für die Release-Liste und die kostenlose /rate_limit-Abfrage. Das Werkzeug liefert weiterhin einen älteren anonymen REST-Abrufer mit, der einen Import eines öffentlichen Repositories im 60-pro-Stunde-Budget schaffte, aber kein CLI-Pfad erreicht ihn noch und er soll gelöscht werden — behandeln Sie --token für direct daher als Pflicht.

Das geteilte Token des Deployments

Senden Sie kein token, setzt der Server das Plattform-Token ein, das sein Betreiber konfiguriert hat (GITHUB_IMPORT_PAT). Drei Grenzen kommen damit mit:

Es ist optionale Konfiguration. Das gehostete eastagiletracker.com stellt eines bereit, dort funktioniert ein Import eines öffentlichen Repositories ohne Token. Eine selbst gehostete Installation — die heruntergeladene Binärdatei — hat keines, bis ihr Betreiber GITHUB_IMPORT_PAT in der Umgebung setzt, und bis dahin lehnt sie jeden Import ohne Token mit 400 import_github_no_token ab.
Es liest nur öffentliche Repositories. Der gehostete Dienst stellt es schreibgeschützt über öffentliche Repos aus, ein privates Repository braucht also immer Ihr eigenes Token.
Alle Aufrufer des Deployments teilen sich ein Budget. Bevor ein Import ohne Token läuft, liest der Server die verbleibenden GraphQL-Punkte des geteilten Tokens und lehnt unterhalb von 500 mit 400 import_github_shared_quota_low ab. Ein Budget, das mitten im Import ausgeht, lässt den Job mit import_github_rate_limited_platform scheitern. Beide Meldungen nennen dieselbe Abhilfe: ein eigenes Token liefern.

Was das Token bringt

GitHub zählt seine beiden APIs getrennt, und die nicht authentifizierte Obergrenze liegt zwei Größenordnungen niedriger.

GitHub-API	Wofür	Mit Token	Ohne Token
GraphQL	Issues, Kommentare, Pull Requests, Sub-Issues, Abhängigkeiten	5.000 Punkte pro Stunde, bewertet nach den Knoten, die eine Abfrage zurückgibt	Abgelehnt — GraphQL hat keine anonyme Stufe
REST	Releases (`include_releases`) und die `/rate_limit`-Vorabprüfung	5.000 Anfragen pro Stunde	60 Anfragen pro Stunde, pro IP-Adresse gezählt und mit allen dahinter geteilt

Ein Import fällt nie auf diese Stufe mit 60 pro Stunde zurück: Ohne ein Token zum Senden wird die Anfrage vorab abgelehnt, statt anonym wiederholt zu werden. Die Zahl zählt für das, was Sie um den Import herum tun — ein Skript, das GitHub direkt liest, oder eine Shell im selben Netz wie andere Clients, verbraucht 60 Anfragen in Sekunden.

Lesen Sie Ihr verbleibendes Budget jederzeit; GET /rate_limit ist von beiden Limits ausgenommen, die Prüfung kostet also nichts:

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

GraphQL-Punkte sind keine Anfragen. GitHub bewertet eine Abfrage nach den Knoten, die sie zurückgibt: Eine Seite mit 100 Issues samt Kommentaren und Zuständigen kostet also viele Punkte, und ein großes Repository gibt das Stundenbudget in weit weniger Aufrufen aus, als die Zahlen aus der REST-Zeit vermuten lassen. --dry-run (Schritt 3) und dry_run (Schritt 4) kosten je dieselben Punkte wie der echte Abruf — das macht ihre Zahlen verlässlich —, planen Sie für einen großen Import also zwei Durchläufe ein.

Wohin als Nächstes

API-Leitfaden — Suchgrammatik, der Ereignisstrom, Massen-Zustandswechsel, idempotente Schreibvorgänge und der Rest der Oberfläche.
Bedienungsanleitung — dieselben Vorgänge aus der Oberfläche, und die anderen zehn Importer.
Einführung — warum die Zustandsmaschine und die vier Story-Typen so geformt sind.
GitHub-to-EAT — das Repository des Importers: jedes Flag, beide Engines, und wie Sie dazu beitragen.