Mengisi projek daripada repo GitHub

Halakan sebuah ejen ke satu repositori GitHub dan anda mendapat semula papan yang boleh terus digunakan: setiap issue menjadi satu story, dalam keadaan yang ditentukan oleh sejarahnya, lengkap dengan senarai semak, label dan tonggak yang dibawa bersama. Kemudian ejen yang sama mengangkat satu story, menuntutnya, menggerakkannya melalui mesin keadaan, dan memautkan pull request yang dibukanya.

Halaman ini menyusuri gelung itu dari hujung ke hujung. Langkah pengisian mempunyai dua laluan: GitHub-to-EAT, pengimport sumber terbuka milik East Agile, menyelesaikannya dengan satu arahan (langkah 3); API import melakukan kerja yang sama panggilan demi panggilan (langkah 4 dan 5), dan itulah yang dipandu oleh ejen apabila ia mahukan pemegang kerja. Segala yang selepas itu berjalan atas API, kerana intinya ialah ejen boleh menyiapkan bakinya tanpa diawasi.

Ini bukan «import AI» yang berasingan. Langkah pengisian ialah pengimport GitHub yang sama, yang boleh anda jalankan sendiri dari Tetapan projek → Import / Eksport, diterangkan dalam Arahan pengendalian → Import daripada tracker lain. Ejen memanggil endpoint yang sama seperti anda. Yang ditambah oleh halaman ini ialah segala yang di sekelilingnya: siapa memegang kunci, bagaimana memeriksa import sebelum ia menulis, dan apa yang ejen lakukan dengan papan setelah papan itu wujud.

Sumber GitHub dalam tab Import / Export: pemilik dan repositori diisi, token dibiarkan kosong, pull request dan milestone ditanda

Apa yang anda perlukan

Sebuah projek — dan satu sesi atau kunci ea_user_… untuk menciptanya.
Sebuah kunci ejen — kunci ea_agent_… yang terhad kepada projek itu. Peranan yang diperlukannya bergantung pada berapa banyak gelung ini yang anda mahu ejen jalankan; lihat langkah 2. Lihat juga Panduan API → Dua jenis kunci.
Sebuah personal access token GitHub — dengan akses baca kepada issues repositori. Setiap import mengesahkan diri, kerana pengambilannya berjalan pada API GraphQL GitHub dan GraphQL menolak permintaan yang tidak membawa token. Anda hanya boleh meninggalkannya apabila Tracker mengambil bagi pihak anda: repositori awam, pada deployment yang mempunyai token sandaran kongsi (perkhidmatan terhos eastagiletracker.com mempunyai satu; pemasangan hos sendiri tiada sehingga pengendalinya menetapkan GITHUB_IMPORT_PAT), dan bukan dengan --engine direct milik GitHub-to-EAT. Lihat Token dan had kadar.
Node.js 22+ — hanya untuk laluan GitHub-to-EAT di langkah 3. Laluan API tidak perlukan apa-apa selain curl.

1. Cipta projek

Projek mesti wujud sebelum kunci ejen, dan mesti dicipta oleh seorang manusia: kunci ejen terikat pada satu projek ketika dijana dan tidak boleh mencipta projek. Ciptalah dalam antara muka, atau dengan kunci ea_user_… anda sendiri:

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

Respons membawa project_id yang diperlukan oleh setiap panggilan di bawah.

2. Jana sebuah kunci ejen

Pemilik projek mencipta kunci ejen di Tetapan projek → Ejen. Peranan yang anda pilih menentukan berapa banyak isi halaman ini yang boleh ejen lakukan sendiri, dan ada dua jawapan yang munasabah:

owner — satu kunci menjalankan seluruh gelung, import sekali. Mengimport hanya untuk pemilik, kerana satu import menulis semula bentuk projek secara menyeluruh. Menjana ejen berperanan owner menuntut anda sendiri pemilik projek: peranan ejen tidak pernah melebihi peranan penciptanya.
member — keistimewaan paling kecil. Ejen menuntut story, menggerakkannya, mengulas dan memautkan pull request, tetapi tidak boleh mengimport. Import anda jalankan sendiri (langkah 5) dengan kunci anda, kemudian papannya diserahkan kepada ejen.

Bagaimanapun juga, jangan biarkan pada nilai lalai. Kunci ejen yang baharu ialah viewer selagi anda tidak berkata lain, dan viewer boleh membaca papan tetapi tidak boleh menuntut atau menggerakkan story — dan itulah sebahagian besar gelung ini.

Kunci ejen penting di sini atas sebab yang melangkaui akses. Sebuah kunci ejen bertindak sebagai peserta bernama dalam satu projek sahaja, jadi setiap story yang diciptanya, setiap perubahan keadaan yang dilakukannya, dan setiap ulasan yang ditulisnya diatributkan kepada ejen itu dalam sejarah — boleh dibezakan daripada kerja anda sendiri dan bukannya bercampur dengannya.

export TRACKER_TOKEN="ea_agent_xxxxx"

Suruh ejen membaca /meta sebelum apa-apa yang lain:

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

Itu menjawab dua soalan yang jika tidak akan diteka ejen: kunci terikat pada projek yang mana (auth.project_id), dan perpindahan keadaan mana yang sah bagi setiap jenis story (transitions). Sebuah feature berjalan unstarted → started → finished → delivered → accepted; sebuah chore hanya unstarted → started → accepted. Membaca petanya mengatasi menulisnya secara tegar dalam kod.

3. Import dengan GitHub-to-EAT

GitHub-to-EAT ialah pengimport sumber terbuka milik East Agile sendiri: sebuah alat baris arahan berlesen MIT yang melakukan seluruh langkah pengisian — langkah 4 dan 5 di bawah — dengan satu arahan. Capailah ia apabila ada manusia di depan terminal. Capailah API di bawahnya apabila ejen memandu tanpa pengawasan dan mahukan pemegang kerja untuk ditinjau.

Ia perlukan Node.js 22+ dan tiada kebergantungan masa jalan sendiri. Ia belum diterbitkan ke npm, jadi pasangkannya daripada repositori:

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

Kemudian halakan ia ke kunci yang anda jana di langkah 2 dan projek yang anda buat di langkah 1:

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

Ia mencetak legenda pemetaan dahulu — tepatnya bagaimana setiap jenis terpilih akan mendarat — dan meminta pengesahan sebelum menulis apa-apa. Di luar terminal, dalam paip, dalam CI atau dalam ejen, tiada tempat untuk memaparkan gesaan itu, jadi larian yang akan menulis mesti menghantar --yes; tanpanya alat itu keluar dengan 2 dan tidak menulis apa-apa, bukannya meneka jawapan anda. Menjalankannya semula selamat: apa yang sudah diimport akan dilangkau, tidak pernah diduplikasi.

Bendera	Apa yang dilakukannya
`--dry-run`	Pemeriksaan awal, kemudian mencetak pelan yang akan dilaksanakannya — berapa banyak story yang akan diimport, berapa banyak yang akan dilangkau kerana sudah ada — dan tidak menulis apa-apa. Tidak perlu `--yes`.
`--include`	Jenis mana untuk diimport, dipisahkan koma: `issues,prs,milestones,releases,deps`. Lalainya `issues`, dan setiap pilihan mesti mengandunginya. Ini pilihan yang sama seperti jadual di langkah 6.
`--token`	Personal access token GitHub anda (`GITHUB_TOKEN` dalam persekitaran atau dalam `.env` turut dikira). Ia perlukan `repo`, atau kebenaran halus Issues: Read, pada repositori itu. Wajib bagi repositori peribadi, bagi pelayan tanpa token sandaran kongsi, dan sentiasa bagi `--engine direct`. Tinggalkan ia pada enjin lalai perkhidmatan terhos maka Tracker membelanjakan bajet kongsinya sendiri — lihat Token dan had kadar.
`--engine`	`server`, yang lalai, menghantar satu panggilan `/import/json` dan membiarkan Tracker mengambil, memetakan dan menulis. `direct` menjalankan talian paip yang sama pada mesin anda dan menulis melalui API awam — jadi ia membaca GitHub sendiri dan sentiasa perlukan token, keluar dengan `2` jika tiada.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Menyempitkan atau menindih pemetaan untuk satu larian; tiada apa yang dikekalkan. Setiap satunya membawa maksud `--engine direct`.

Tetapkan EAT_API_BASE dan EAT_APP_BASE untuk menghalakannya ke Tracker hos sendiri atau setempat; kedua-duanya secara lalai menunjuk ke perkhidmatan terhos. README membawa rujukan bendera yang penuh, kod keluar, dan penyelesaian masalah.

Semua di bawah ini ialah import yang sama, dipandu panggilan demi panggilan, dan itulah yang anda mahu apabila ejen yang menjalankannya.

4. Larian kering dahulu

Mengimport ialah hanya untuk pemilik — gunakan kunci ejen berperanan owner, atau kunci anda sendiri jika anda membiarkan ejen sebagai member. Jalankannya dengan dry_run dahulu, sebelum anda membiarkannya menulis apa-apa:

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

Sebuah larian kering mengambil daripada GitHub, menyelesaikan dan menyahduplikasi tepat seperti yang sebenar, melaporkan kiraan yang sama — imported, skipped, errors, unmatched — dan kemudian mengundurkan seluruh transaksi. Tiada apa yang kekal dan tiada peristiwa import selesai sampai ke log audit anda. Ia cara paling murah untuk mengetahui bahawa anda sebenarnya mahu memasukkan tonggak, atau bahawa sebuah repo lebih besar daripada sangkaan anda, sementara ia masih tidak berbelanja apa-apa.

Setiap panggilan ke /import/json bersifat tak segerak, termasuk larian kering: endpoint memulangkan 202 dengan pemegang kerja, bukan hasil, dan kiraan tiba pada kerja itu apabila anda meninjaunya (langkah 5). Kerja bagi larian kering mencapai done seperti yang sebenar; bezanya ialah tiada apa-apa yang ditulis.

5. Jalankan import

Buang dry_run dan hantar semula. Seperti sebelum ini, endpoint memulangkan 202 dengan pemegang kerja:

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

Tinjau kerja itu sehingga ia mencapai keadaan akhir:

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

Status berjalan pending → fetching → writing → done | failed. Hanya dua yang terakhir bersifat akhir: done membawa kiraan hasil, failed membawa mesej ralat dan kod mesin yang stabil untuk anda bercabang. Semasa pengambilan menghalaman, progress_current dan progress_total memberitahu ia berada di halaman mana — berbaloi dipaparkan jika ada manusia memerhati.

Token. Hantar "token": "github_pat_…". Tinggalkannya dan pelayan menggantikannya dengan token platform kongsi, yang hanya membaca repositori awam dan bajetnya ditolak merentas setiap pemanggil pada deployment itu — Token dan had kadar menerangkan harganya bagi anda. Token mana pun yang digunakan, ia memacu panggilan GitHub huluan dan tiada yang lain: ia tidak pernah dilog, tidak pernah masuk log audit, tidak pernah disimpan, dan tidak pernah digemakan kembali dalam respons atau ralat.

Menjalankannya semula selamat. Baris yang sudah pernah diimport dipadankan melalui id sumbernya lalu dilangkau, bukan diduplikasi. Import kedua melengkapkan papan dengan apa yang muncul sejak yang pertama.

6. Apa yang mendarat di papan

Issues diimport secara lalai. Selebihnya adalah pilih-masuk, satu bendera bagi setiap jenis:

Daripada GitHub	Menjadi	Bendera
Issue	Sebuah story. Terbuka → unstarted dalam Backlog. Tertutup → accepted, atau rejected apabila GitHub menyatakan issue ditutup sebagai `not_planned` atau `duplicate` (story kemudiannya membawa label yang sepadan).	lalai
Senarai semak dalam badan issue	Tugasan — setiap baris `- [ ]` / `- [x]` menjadi satu tugasan mengikut susunan badan, dan `[x]` tiba dalam keadaan selesai. Senarai semak itu turut kekal dalam penerangan.	lalai
Label	Label, dibawa seadanya.	lalai
Pull request	Sebuah story berlabel `pull-request`. Terbuka → started, tercantum → accepted, ditutup tanpa cantuman → rejected.	`include_pull_requests`
Tonggak	Sebuah epik, dinamakan menurut tonggaknya, dinyahduplikasi mengikut tajuk — dua issue yang berkongsi tonggak mendarat dalam satu epik. Dengan bendera dimatikan, ia ikut sebagai label `milestone:<tajuk>`.	`include_milestones`
Release	Sebuah story release. Diterbitkan → accepted, draf → unstarted.	`include_releases`
Kebergantungan issue	Sebuah blocker pada story. Issue sahaja, tidak pernah pull request.	`include_dependencies`

Jenis story disimpulkan apabila issue tidak menyatakannya. Label yang mengandungi bug, fix atau defect — atau tajuk yang bermula dengan fix atau bug — menjadikannya bug; chore, maintenance, devops atau infra menjadikannya chore; selain itu ialah feature. Ini berbaloi diketahui sebelum mengimport, kerana dalam East Agile Tracker hanya feature membawa point dan hanya feature menyuap velocity. Lihat Pengenalan → Story.

Papan projek sejurus selepas mengimport repositori contoh: isu sebagai story dengan labelnya, milestone sebagai epik dan orang GitHub sebagai pemilik

7. Ejen mengerjakan sebuah story

Kini papan sudah mempunyai sejarah, dan ejen sudah mempunyai kunci. Gelung dari sini ialah empat panggilan.

Cari sebuah story, atau tulis satu. Tapis papan untuk sesuatu yang boleh diangkat:

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

import_source=github menyempitkannya kepada apa yang dibawa masuk oleh import. Jika ejen menjumpai kerja yang tidak pernah ditangkap oleh repo, ia mencipta story itu sendiri — lihat Panduan API → Cipta sebuah story.

Tuntut story itu. Sebuah ejen menambah dirinya sebagai pemilik dengan mem-POST badan kosong:

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

Badan kosong bermaksud si pemanggil, jadi ejen tidak perlu tahu id-nya sendiri. Papan kini menunjukkan ejen sebagai pemilik, dan daripada situ manusia yang memerhati tahu kerja itu sudah diambil.

Mulakan story itu.

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

Kemudian ejen pergi melakukan kerja itu — membaca repo, menulis kod, membuka pull request. Bahagian itu berlaku dalam alat pengaturcaraan anda, bukan di sini.

Lampirkan 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 request GitHub dikenali sebagai sedemikian — anda tidak perlu menyebutnya. Story dan kod yang menutupnya kini berjarak satu klik antara satu sama lain, dalam kedua-dua arah.

Selesaikan story itu. Pindahkan ke finished dan berhenti di situ. Sebuah feature masih ada delivered dan accepted di hadapannya, dan itulah pintu semakan: seseorang selain ejen memutuskan bahawa kerja itu betul. Sebuah chore tiada pintu sedemikian — started → accepted ialah keseluruhan baki jalannya.

Isu tertutup yang diimport dengan bahagian CODE memautkan pull request yang membaikinya, bersama komen GitHub di sebelahnya

Token dan had kadar

Setiap import mengesahkan diri. Pengambilan issue, ulasan dan pull request berjalan pada API GraphQL GitHub, dan GraphQL menolak permintaan yang tidak membawa token — tiada peringkat tanpa nama, sama ada pada repositori awam atau peribadi. Persoalannya tidak pernah sama ada sebuah token sampai ke GitHub, hanya milik siapa.

Token anda sendiri

Hantar token pada panggilan import, atau --token kepada GitHub-to-EAT. Sebuah personal access token berbutir halus dengan akses baca kepada issues repositori sudah memadai. Ia memacu panggilan GitHub huluan dan tiada yang lain: ia tidak pernah dilog, tidak pernah masuk log audit, tidak pernah disimpan, dan tidak pernah digemakan kembali dalam respons atau ralat.

Bawalah token anda sendiri untuk apa-apa yang melangkaui demo. Anda kemudiannya membelanjakan bajet yang tidak disentuh sesiapa, dan tiada pemeriksaan awal yang boleh menolak anda kerana import orang lain.

--engine direct tidak meninggalkan anda pilihan. Enjin itu membaca GitHub daripada mesin anda dan bukannya melalui Tracker, jadi token pelayan berada di luar jangkauan; larian tanpa token keluar dengan 2 disertai ralat penggunaan sebelum ia mengambil atau menulis apa-apa. GITHUB_TOKEN dalam persekitaran atau .env anda turut dikira, sama seperti --token.

Yang mewajibkan token ialah penelusuran issues, bukan keseluruhan enjin. direct membaca issues, komen dan pull request melalui GraphQL, yang tiada mod tanpa nama; ia menyentuh REST hanya untuk senarai releases dan pemeriksaan percuma /rate_limit. Alat ini masih menyertakan pengambil REST tanpa nama yang lebih lama, yang menjalankan import repositori awam dalam bajet 60 sejam, tetapi tiada laluan CLI mencapainya lagi dan ia bakal dipadam — jadi anggap --token wajib untuk direct.

Token kongsi deployment

Jangan hantar sebarang token dan pelayan menggantikannya dengan token platform yang dikonfigurasi pengendalinya (GITHUB_IMPORT_PAT). Tiga had ikut bersamanya:

Ia konfigurasi pilihan. Perkhidmatan terhos eastagiletracker.com menyediakan satu, jadi import repositori awam tanpa token berfungsi di sana. Pemasangan hos sendiri — binari yang dimuat turun — tiada sehingga pengendalinya menetapkan GITHUB_IMPORT_PAT dalam persekitaran, dan sehingga itu ia menolak setiap import tanpa token dengan 400 import_github_no_token.
Ia hanya membaca repositori awam. Perkhidmatan terhos menjananya baca-sahaja atas repo awam, jadi repositori peribadi sentiasa perlukan token anda sendiri.
Setiap pemanggil pada deployment berkongsi satu bajet. Sebelum import tanpa token berjalan, pelayan membaca baki mata GraphQL token kongsi itu dan menolak dengan 400 import_github_shared_quota_low di bawah 500. Bajet yang habis di tengah import menggagalkan kerja itu dengan import_github_rate_limited_platform. Kedua-dua mesej menyebut pembetulan yang sama: sediakan token anda sendiri.

Apa yang dibeli oleh token

GitHub mengukur kedua-dua API-nya secara berasingan, dan siling tanpa pengesahan dua darjah magnitud lebih rendah.

API GitHub	Digunakan untuk	Dengan token	Tanpa token
GraphQL	Issue, ulasan, pull request, sub-issue, kebergantungan	5,000 mata sejam, dimarkahkan atas nod yang dipulangkan oleh pertanyaan	Ditolak — GraphQL tiada peringkat tanpa nama
REST	Release (`include_releases`), dan pemeriksaan awal `/rate_limit`	5,000 permintaan sejam	60 permintaan sejam, dikira per alamat IP dan dikongsi dengan semua yang di belakangnya

Sebuah import tidak pernah jatuh ke peringkat 60 sejam itu: tanpa token untuk dihantar, permintaan itu ditolak awal-awal dan bukannya dicuba semula secara tanpa nama. Angka itu penting bagi apa yang anda lakukan di sekeliling import — sebuah skrip yang membaca GitHub terus, atau sebuah shell dalam rangkaian yang sama dengan klien lain, menghabiskan 60 permintaan dalam beberapa saat.

Baca baki bajet anda bila-bila masa; GET /rate_limit dikecualikan daripada kedua-dua had, jadi pemeriksaan itu tidak berbelanja apa-apa:

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

Mata GraphQL bukan permintaan. GitHub memarkahkan sesuatu pertanyaan atas nod yang dipulangkannya, jadi satu halaman berisi 100 issue berserta ulasan dan penerima tugasnya sudah memakan banyak mata, dan repositori besar membelanjakan bajet sejam dalam jauh lebih sedikit panggilan daripada yang dicadangkan angka-angka era REST. --dry-run (langkah 3) dan dry_run (langkah 4) masing-masing memakan mata yang sama dengan pengambilan sebenar — itulah yang menjadikan kiraan mereka boleh dipercayai — jadi peruntukkan dua pusingan apabila anda memeriksa awal sebuah import yang besar.

Ke mana selepas ini

Panduan API — tatabahasa carian, strim peristiwa, peralihan pukal, tulisan idempoten, dan baki permukaannya.
Arahan pengendalian — operasi yang sama daripada antara muka, dan sepuluh pengimport yang lain.
Pengenalan — mengapa mesin keadaan dan keempat-empat jenis story berbentuk sebegini.
GitHub-to-EAT — repositori pengimport itu sendiri: setiap bendera, kedua-dua enjin, dan cara menyumbang kepadanya.