Mengisi proyek dari repo GitHub

Arahkan sebuah agen ke satu repositori GitHub dan Anda mendapat papan yang siap dipakai: setiap issue menjadi satu story, dalam status yang ditentukan riwayatnya, lengkap dengan checklist, label, dan milestone yang ikut terbawa. Lalu agen yang sama memungut satu story, mengklaimnya, menggerakkannya melewati mesin status, dan menautkan pull request yang ia buka.

Halaman ini menelusuri lingkaran itu dari ujung ke ujung. Langkah pengisian punya dua jalur: GitHub-to-EAT, importer sumber terbuka milik East Agile, menyelesaikannya dalam satu perintah (langkah 3); API impor mengerjakan hal yang sama panggilan demi panggilan (langkah 4 dan 5), dan itulah yang dikemudikan agen ketika ia mau pegangan job. Semua sesudah itu berjalan di atas API, karena intinya justru agar sisanya bisa dikerjakan agen tanpa diawasi.

Ini bukan «impor AI» yang terpisah. Langkah pengisian memakai importer GitHub yang sama, yang bisa Anda jalankan manual dari Pengaturan proyek → Impor / Ekspor, dijelaskan di Petunjuk pengoperasian → Mengimpor dari tracker lain. Agen memanggil endpoint yang sama seperti Anda. Yang ditambahkan halaman ini adalah segala hal di sekitarnya: siapa yang memegang kunci, bagaimana memeriksa impor sebelum ia menulis, dan apa yang agen lakukan dengan papan setelah papan itu ada.

Sumber GitHub di tab Import / Export: pemilik dan repositori terisi, token dibiarkan kosong, pull request dan milestone dicentang

Yang Anda perlukan

Sebuah proyek — dan sesi atau kunci ea_user_… untuk membuatnya.
Sebuah kunci agen — kunci ea_agent_… yang dibatasi pada proyek itu. Peran yang dibutuhkan tergantung seberapa banyak lingkaran ini ingin Anda serahkan ke agen; lihat langkah 2. Lihat juga Panduan API → Dua jenis kunci.
Sebuah personal access token GitHub — dengan akses baca ke issue repositori. Setiap impor melakukan autentikasi, karena pengambilannya berjalan di API GraphQL GitHub dan GraphQL menolak permintaan tanpa token. Anda hanya boleh menghilangkannya bila Tracker mengambil atas nama Anda: repositori publik, pada deployment yang punya token cadangan bersama (layanan terkelola eastagiletracker.com punya satu; instalasi mandiri tidak punya sampai operatornya menetapkan GITHUB_IMPORT_PAT), dan bukan dengan --engine direct milik GitHub-to-EAT. Lihat Token dan batas laju.
Node.js 22+ — hanya untuk jalur GitHub-to-EAT di langkah 3. Jalur API tidak butuh apa pun selain curl.

1. Buat proyeknya

Proyek harus ada sebelum kunci agen ada, dan harus dibuat oleh orang: kunci agen terikat pada satu proyek saat dicetak dan tidak bisa membuat proyek. Buat lewat antarmuka, 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 dibutuhkan setiap panggilan di bawah.

2. Cetak sebuah kunci agen

Pemilik proyek membuat kunci agen di Pengaturan proyek → Agen. Peran yang Anda pilih menentukan seberapa banyak isi halaman ini bisa dikerjakan agen sendiri, dan ada dua jawaban yang masuk akal:

owner — satu kunci menjalankan seluruh lingkaran, termasuk impor. Mengimpor hanya untuk pemilik, karena satu impor menulis ulang bentuk proyek secara menyeluruh. Mencetak agen berperan owner mensyaratkan Anda sendiri pemilik proyek: peran agen tidak pernah melampaui peran pembuatnya.
member — hak paling kecil. Agen mengklaim story, memindahkannya, berkomentar, dan menautkan pull request, tetapi tidak bisa mengimpor. Impor Anda jalankan sendiri (langkah 5) dengan kunci Anda, lalu papannya diserahkan ke agen.

Bagaimanapun, jangan biarkan di nilai bawaan. Kunci agen yang baru adalah viewer sampai Anda berkata lain, dan viewer bisa membaca papan tetapi tidak bisa mengklaim atau memindahkan story — dan itu sebagian besar dari lingkaran ini.

Kunci agen penting di sini karena alasan yang melampaui akses. Sebuah kunci agen bertindak sebagai peserta bernama dalam satu proyek, jadi setiap story yang ia buat, setiap perubahan status yang ia lakukan, dan setiap komentar yang ia tulis diatribusikan ke agen itu dalam riwayat — bisa dibedakan dari pekerjaan Anda sendiri alih-alih melebur ke dalamnya.

export TRACKER_TOKEN="ea_agent_xxxxx"

Suruh agen membaca /meta sebelum apa pun yang lain:

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

Itu menjawab dua pertanyaan yang kalau tidak akan ditebak-tebak agen: kunci terikat ke proyek yang mana (auth.project_id), dan perpindahan status apa yang sah untuk tiap tipe story (transitions). Sebuah feature berjalan unstarted → started → finished → delivered → accepted; sebuah chore hanya unstarted → started → accepted. Membaca petanya lebih baik daripada menuliskannya secara kaku di kode.

3. Impor dengan GitHub-to-EAT

GitHub-to-EAT adalah importer sumber terbuka milik East Agile sendiri: alat baris perintah berlisensi MIT yang mengerjakan seluruh langkah pengisian — langkah 4 dan 5 di bawah — dalam satu perintah. Pakai ini kalau ada orang di depan terminal. Pakai API di bawahnya kalau yang mengemudi adalah agen tanpa pengawasan dan ia mau pegangan job untuk dipantau.

Ia butuh Node.js 22+ dan tidak punya dependensi runtime sendiri. Belum diterbitkan ke npm, jadi pasang dari repositorinya:

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

Lalu arahkan ke kunci yang Anda cetak di langkah 2 dan proyek 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 lebih dulu — persisnya bagaimana tiap tipe terpilih akan mendarat — dan meminta konfirmasi sebelum menulis apa pun. Di luar terminal, dalam pipe, di CI, atau di dalam agen, tidak ada tempat menampilkan prompt itu, jadi jalannya yang akan menulis harus mengirim --yes; tanpa itu alat keluar dengan 2 dan tidak menulis apa-apa alih-alih menebak jawaban Anda. Menjalankan ulang aman: yang sudah diimpor akan dilewati, tidak pernah diduplikasi.

Flag	Apa yang dilakukannya
`--dry-run`	Pemeriksaan awal, lalu mencetak rencana yang akan dijalankannya — berapa story yang akan diimpor, berapa yang akan dilewati karena sudah ada — dan tidak menulis apa pun. Tidak butuh `--yes`.
`--include`	Tipe apa saja yang diimpor, dipisah koma: `issues,prs,milestones,releases,deps`. Bawaannya `issues`, dan setiap pilihan harus memuatnya. Ini opsi yang sama dengan tabel di langkah 6.
`--token`	Personal access token GitHub Anda (`GITHUB_TOKEN` di lingkungan atau di `.env` juga dihitung). Ia butuh `repo`, atau izin halus Issues: Read, pada repositori itu. Wajib untuk repositori privat, untuk server tanpa token cadangan bersama, dan selalu untuk `--engine direct`. Hilangkan pada mesin bawaan layanan terkelola, maka Tracker memakai anggaran bersamanya sendiri — lihat Token dan batas laju.
`--engine`	`server`, yang bawaan, mengirim satu panggilan `/import/json` dan membiarkan Tracker mengambil, memetakan, dan menulis. `direct` menjalankan pipeline yang sama di mesin Anda dan menulis lewat API publik — jadi ia membaca GitHub sendiri dan selalu butuh token, keluar dengan `2` kalau tidak ada.
`--states`, `--milestones`, `--story-type`, `--no-comments`, `--no-tasks`	Mempersempit atau menimpa pemetaan untuk satu jalan; tidak ada yang disimpan. Masing-masing menyiratkan `--engine direct`.

Setel EAT_API_BASE dan EAT_APP_BASE untuk mengarahkannya ke Tracker swa-kelola atau lokal; keduanya bawaannya menunjuk layanan terkelola. README memuat rujukan flag lengkap, kode keluar, dan penanganan masalah.

Semua di bawah ini adalah impor yang sama, dikemudikan panggilan demi panggilan, dan itulah yang Anda mau ketika sebuah agen menjalankannya.

4. Coba kering dulu

Mengimpor hanya untuk pemilik — pakai kunci agen berperan owner, atau kunci Anda sendiri kalau agen Anda biarkan sebagai member. Jalankan dulu dengan dry_run, sebelum Anda biarkan ia menulis apa pun:

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 coba kering mengambil dari GitHub, menyelesaikan, dan mendeduplikasi persis seperti yang sungguhan, melaporkan hitungan yang sama — imported, skipped, errors, unmatched — lalu membatalkan seluruh transaksi. Tidak ada yang bertahan dan tidak ada peristiwa impor selesai yang sampai ke log audit Anda. Ini cara paling murah untuk tahu bahwa Anda sebenarnya ingin ikut memasukkan milestone, atau bahwa sebuah repo lebih besar dari dugaan Anda, selagi itu belum memakan biaya apa pun.

Setiap panggilan ke /import/json bersifat asinkron, termasuk coba kering: endpoint mengembalikan 202 dengan pegangan job, bukan hasil, dan hitungannya tiba pada job ketika Anda mem-poll-nya (langkah 5). Job coba kering mencapai done seperti yang sungguhan; bedanya adalah tidak ada yang ditulis.

5. Jalankan impornya

Buang dry_run dan kirim lagi. Seperti sebelumnya, endpoint mengembalikan 202 dengan pegangan job:

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

Pantau job sampai ia mencapai status 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 yang final: done membawa hitungan hasil, failed membawa pesan galat dan kode mesin stabil yang bisa Anda cabangkan. Selagi pengambilan memaginasi, progress_current dan progress_total memberi tahu ia di halaman berapa — layak ditampilkan kalau ada orang yang menonton.

Token. Kirim "token": "github_pat_…". Hilangkan dan server memakai token platform bersama, yang hanya membaca repositori publik dan anggarannya dibebankan ke setiap pemanggil pada deployment itu — Token dan batas laju menjelaskan apa harganya bagi Anda. Token mana pun yang dipakai, ia menggerakkan panggilan GitHub hulu dan tidak lebih: ia tidak pernah masuk log, tidak pernah masuk log audit, tidak pernah disimpan, dan tidak pernah digemakan kembali dalam respons atau galat.

Menjalankan ulang aman. Baris yang sudah pernah diimpor dicocokkan lewat id sumbernya lalu dilewati, bukan diduplikasi. Impor kedua melengkapi papan dengan apa yang muncul sejak impor pertama.

6. Apa yang mendarat di papan

Issue diimpor secara bawaan. Selebihnya bersifat opsional, satu flag per tipe:

Dari GitHub	Menjadi	Flag
Issue	Sebuah story. Terbuka → unstarted di Backlog. Tertutup → accepted, atau rejected ketika GitHub menyatakan issue ditutup sebagai `not_planned` atau `duplicate` (story lalu membawa label yang sesuai).	bawaan
Checklist di badan issue	Tugas — setiap baris `- [ ]` / `- [x]` menjadi satu tugas sesuai urutan badan, dan `[x]` tiba dalam keadaan selesai. Checklist juga tetap ada di deskripsi.	bawaan
Label	Label, dibawa apa adanya.	bawaan
Pull request	Sebuah story berlabel `pull-request`. Terbuka → started, tergabung → accepted, tertutup tanpa penggabungan → rejected.	`include_pull_requests`
Milestone	Sebuah epik, dinamai menurut milestone-nya, dideduplikasi berdasarkan judul — dua issue yang berbagi milestone mendarat di satu epik. Dengan flag mati, ia ikut sebagai label `milestone:<judul>`.	`include_milestones`
Rilis	Sebuah story rilis. Terbit → accepted, draf → unstarted.	`include_releases`
Ketergantungan issue	Sebuah blocker pada story. Hanya issue, tidak pernah pull request.	`include_dependencies`

Tipe story disimpulkan ketika issue tidak menyebutkannya. Label yang memuat bug, fix, atau defect — atau judul yang diawali fix atau bug — menjadikannya bug; chore, maintenance, devops, atau infra menjadikannya chore; selain itu feature. Ini layak diketahui sebelum mengimpor, karena di East Agile Tracker hanya feature yang membawa point dan hanya feature yang mengisi velocity. Lihat Pengantar → Story.

Papan proyek tepat setelah mengimpor repositori contoh: issue menjadi story beserta labelnya, milestone menjadi epic, dan orang GitHub menjadi pemilik

7. Agen mengerjakan sebuah story

Kini papan sudah punya riwayat, dan agen sudah punya kunci. Lingkaran dari sini adalah empat panggilan.

Cari sebuah story, atau tulis satu. Saring papan untuk sesuatu yang bisa dipungut:

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

import_source=github mempersempitnya ke apa yang dibawa masuk oleh impor. Kalau agen menemukan pekerjaan yang tak pernah tercatat di repo, ia membuat story-nya sendiri — lihat Panduan API → Membuat story.

Klaim story itu. Sebuah agen menambahkan 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 berarti si pemanggil, jadi agen tidak perlu tahu id-nya sendiri. Papan kini menampilkan agen sebagai pemilik, dan dari situ orang yang menonton tahu pekerjaan itu sudah diambil.

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

Lalu agen pergi mengerjakannya — membaca repo, menulis kode, membuka pull request. Bagian itu terjadi di alat pemrograman Anda, bukan di sini.

Lampirkan pull request-nya.

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 sebagaimana adanya — Anda tidak perlu menyebutkannya. Story dan kode yang menutupnya kini berjarak satu klik, ke kedua arah.

Selesaikan story itu. Pindahkan ke finished lalu berhenti di situ. Sebuah feature masih punya delivered dan accepted di depannya, dan itulah gerbang tinjauan: seseorang selain agen yang memutuskan pekerjaannya sudah benar. Sebuah chore tidak punya gerbang itu — started → accepted adalah seluruh sisa jalannya.

Issue tertutup hasil impor yang bagian CODE-nya menautkan pull request yang memperbaikinya, dengan komentar GitHub di sampingnya

Token dan batas laju

Setiap impor melakukan autentikasi. Pengambilan issue, komentar, dan pull request berjalan di API GraphQL GitHub, dan GraphQL menolak permintaan tanpa token — tidak ada tingkat anonim, baik pada repositori publik maupun privat. Pertanyaannya tidak pernah apakah ada token yang sampai ke GitHub, hanya milik siapa.

Token Anda sendiri

Kirim token pada panggilan impor, atau --token ke GitHub-to-EAT. Sebuah personal access token berbutir halus dengan akses baca ke issue repositori sudah cukup. Ia menggerakkan panggilan GitHub hulu dan tidak lebih: tidak pernah masuk log, tidak pernah masuk log audit, tidak pernah disimpan, dan tidak pernah digemakan kembali dalam respons atau galat.

Bawa token Anda sendiri untuk apa pun di luar sekadar demo. Dengan begitu Anda memakai anggaran yang tak disentuh siapa pun, dan tak ada pemeriksaan awal yang bisa menolak Anda gara-gara impor orang lain.

--engine direct tidak memberi Anda pilihan. Mesin itu membaca GitHub dari mesin Anda, bukan lewat Tracker, jadi token server berada di luar jangkauan; jalan tanpa token keluar dengan 2 disertai galat penggunaan sebelum ia mengambil atau menulis apa pun. GITHUB_TOKEN di lingkungan atau .env Anda dihitung, sama seperti --token.

Yang memaksa token adalah penelusuran issue, bukan seluruh mesin. direct membaca issue, komentar, dan pull request lewat GraphQL, yang tidak punya mode anonim; ia menyentuh REST hanya untuk daftar releases dan sonda gratis /rate_limit. Alat ini masih menyertakan pengambil REST anonim lama yang menjalankan impor repositori publik dalam anggaran 60 per jam, tetapi tidak ada jalur CLI yang mencapainya lagi dan ia akan dihapus — jadi anggap --token wajib untuk direct.

Token bersama milik deployment

Jangan kirim token sama sekali dan server akan memakai token platform yang dikonfigurasi operatornya (GITHUB_IMPORT_PAT). Tiga batasan ikut bersamanya:

Ini konfigurasi opsional. Layanan terkelola eastagiletracker.com menyediakan satu, jadi impor repositori publik tanpa token berhasil di sana. Instalasi mandiri — biner yang diunduh — tidak punya sampai operatornya menetapkan GITHUB_IMPORT_PAT di lingkungan, dan sampai saat itu ia menolak setiap impor tanpa token dengan 400 import_github_no_token.
Ia hanya membaca repositori publik. Layanan terkelola mencetaknya hanya-baca atas repo publik, jadi repositori privat selalu butuh token Anda sendiri.
Setiap pemanggil pada deployment berbagi satu anggaran. Sebelum impor tanpa token berjalan, server membaca sisa poin GraphQL token bersama dan menolak dengan 400 import_github_shared_quota_low di bawah 500. Anggaran yang habis di tengah impor menggagalkan job dengan import_github_rate_limited_platform. Kedua pesan menyebut perbaikan yang sama: sediakan token Anda sendiri.

Apa yang dibeli token

GitHub mengukur kedua API-nya secara terpisah, dan plafon tanpa autentikasi dua orde besaran lebih rendah.

API GitHub	Dipakai untuk	Dengan token	Tanpa token
GraphQL	Issue, komentar, pull request, sub-issue, ketergantungan	5.000 poin per jam, dinilai atas simpul yang dikembalikan kueri	Ditolak — GraphQL tidak punya tingkat anonim
REST	Rilis (`include_releases`) dan pemeriksaan awal `/rate_limit`	5.000 permintaan per jam	60 permintaan per jam, dihitung per alamat IP dan dibagi dengan semua yang ada di belakangnya

Sebuah impor tidak pernah jatuh ke tingkat 60 per jam itu: karena tidak ada token untuk dikirim, permintaannya ditolak di muka alih-alih diulang secara anonim. Angka itu penting untuk apa yang Anda lakukan di sekitar impor — sebuah skrip yang membaca GitHub langsung, atau sebuah shell di jaringan yang sama dengan klien lain, menghabiskan 60 permintaan dalam hitungan detik.

Baca sisa anggaran Anda kapan saja; GET /rate_limit dikecualikan dari kedua batas, jadi pemeriksaannya tidak memakan biaya:

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

Poin GraphQL bukan permintaan. GitHub menilai sebuah kueri atas simpul yang dikembalikannya, jadi satu halaman berisi 100 issue beserta komentar dan penanggung jawabnya sudah memakan banyak poin, dan repositori besar menghabiskan anggaran per jam dalam jauh lebih sedikit panggilan daripada yang disiratkan angka-angka era REST. --dry-run (langkah 3) dan dry_run (langkah 4) masing-masing memakan poin yang sama dengan pengambilan sungguhan — justru itu yang membuat hitungannya bisa dipercaya — jadi anggarkan dua lintasan ketika Anda memeriksa awal sebuah impor besar.

Ke mana selanjutnya

Panduan API — tata bahasa pencarian, aliran peristiwa, transisi massal, penulisan idempoten, dan sisa permukaannya.
Petunjuk pengoperasian — operasi yang sama dari antarmuka, dan sepuluh importer lainnya.
Pengantar — mengapa mesin status dan keempat tipe story berbentuk seperti ini.
GitHub-to-EAT — repositori importer itu sendiri: setiap flag, kedua mesin, dan cara berkontribusi padanya.