Migrasi workflow Git tim ke forge mandiri tanpa mengganggu CI bukan terutama soal memindahkan repository, melainkan memindahkan seluruh permukaan integrasi yang selama ini menempel pada platform lama: pull request, issue, webhook, runner, release, registry, autentikasi, dan secret. Jika migrasi dilakukan hanya dengan git push --mirror, repo memang pindah, tetapi alur kerja tim biasanya rusak di titik lain.

Untuk tim kecil-menengah, pendekatan yang paling aman adalah migrasi bertahap: audit dependensi workflow saat ini, jadikan forge baru sebagai target sinkronisasi awal, pindahkan CI dan integrasi secara terkontrol, lalu ubah perilaku developer setelah bukti stabilitas cukup kuat. Konteks tren seperti “One year with Codeberg” menunjukkan bahwa banyak tim mulai serius mengevaluasi forge mandiri atau federatif, tetapi keputusan teknis yang sehat tetap harus vendor-agnostik dan berfokus pada kontinuitas kerja.

Apa yang sebenarnya dipindahkan saat migrasi forge

Sebelum menyusun rencana, anggap forge sebagai gabungan beberapa layanan, bukan satu aplikasi. Repository Git hanya salah satu komponennya. Daftar berikut biasanya menentukan apakah migrasi berjalan mulus atau justru menimbulkan gangguan tersembunyi.

1. Repository dan model branch

  • Remote Git utama dan mirror.
  • Branch default, branch protection, aturan merge, dan penamaan tag.
  • Submodule, Git LFS, atau monorepo tooling jika digunakan.

2. Issue, pull request, dan diskusi review

  • Issue aktif yang masih menjadi referensi sprint atau incident.
  • PR yang sedang dibahas atau menunggu merge.
  • Tautan otomatis dari commit ke issue/PR.
  • Template issue, template PR, label, milestone, dan assignee.

3. Webhook dan integrasi eksternal

  • Webhook ke CI, chat, deployment, incident management, atau sistem internal.
  • Status check yang dikirim kembali ke platform forge.
  • Bot yang membuat komentar, label, atau auto-merge.

4. Runner dan eksekusi CI

  • Tempat job berjalan: runner terkelola, self-hosted runner, atau sistem CI eksternal.
  • Dependensi ke syntax YAML spesifik vendor.
  • Cache, artefak, image container, concurrency, dan matriks build.

5. Release dan artefak distribusi

  • Tag yang memicu release otomatis.
  • Binary, checksum, changelog, atau SBOM yang diunggah saat release.
  • Tautan unduhan yang sudah dipakai pengguna internal atau pelanggan.

6. Package registry

  • Registry container, npm, Maven, PyPI, Helm, atau paket privat lain.
  • Kredensial publish/pull di pipeline dan workstation developer.
  • Dependensi proyek lain yang menarik paket dari platform lama.

7. Autentikasi dan otorisasi

  • SSO, OAuth app, deploy key, SSH key, token bot, dan PAT.
  • Mapping peran tim ke repo atau organisasi.
  • Aturan audit log dan akses minimal.

Kesalahan umum adalah fokus hanya pada repo dan CI, lalu baru sadar di akhir bahwa image container masih dipublish ke registry lama, atau bot rilis masih bergantung pada token platform lama.

Audit dependensi workflow saat ini

Sebelum memilih tanggal migrasi, buat inventaris dependensi. Tujuannya sederhana: tahu mana yang harus dipindah, mana yang bisa dipertahankan sementara, dan mana yang sebaiknya diputus dulu karena terlalu mahal dipindahkan pada tahap awal.

Pertanyaan audit yang wajib dijawab

  • Di mana repo canonical berada hari ini?
  • Apakah semua pipeline dipicu dari event platform lama, atau ada CI eksternal yang hanya butuh webhook?
  • Apakah merge harus menunggu status check dari platform tertentu?
  • Issue dan PR mana yang benar-benar masih aktif?
  • Apakah release mengambil artefak dari CI atau dari fitur release bawaan platform?
  • Apakah package registry lama dipakai oleh proyek lain di luar tim?
  • Siapa pemilik token, secret, dan bot account?
  • Apa prosedur rollback jika commit penting tidak tersinkron?

Format audit yang praktis

Untuk tim kecil-menengah, spreadsheet atau dokumen tabel sudah cukup. Minimal kolomnya:

  • Komponen: repo, issue, CI, registry, webhook, auth.
  • Sistem saat ini: platform lama, tool pihak ketiga, atau internal.
  • Ketergantungan: token, endpoint, syntax YAML, bot.
  • Strategi migrasi: pindah penuh, mirror sementara, tetap dipakai dulu.
  • Risiko: kehilangan histori, downtime CI, gagal publish.
  • PIC: siapa yang bertanggung jawab.

Jika Anda belum punya daftar ini, kemungkinan besar Anda belum siap migrasi. Audit lebih murah daripada memperbaiki pipeline yang diam-diam berhenti berjalan setelah cutover.

Strategi migrasi bertahap yang aman

Pendekatan vendor-agnostik yang realistis biasanya terdiri dari empat fase: persiapan, mirror, transisi workflow, dan cutover. Dengan pola ini, tim bisa mengurangi risiko tanpa membekukan pekerjaan terlalu lama.

Fase 1: Persiapan forge baru

  • Buat organisasi/grup dan repo target.
  • Atur akses SSH dan token bot khusus automasi, jangan pakai akun pribadi.
  • Konfigurasikan branch default, branch protection, dan struktur tim.
  • Aktifkan fitur minimum yang dibutuhkan: issue tracker, release, registry jika dipakai.

Pada tahap ini, jangan buru-buru memindahkan semua proses. Fokus pada fondasi: akses, permission, dan jalur push yang konsisten.

Fase 2: Mirror repository terlebih dahulu

Langkah paling aman adalah membuat forge baru menerima sinkronisasi dari repo lama sampai tim siap menjadikannya canonical. Ini memberi waktu untuk menguji integrasi tanpa memaksa semua developer berubah di hari yang sama.

git clone --mirror [email protected]:team/app.git
cd app.git
git remote add new [email protected]:team/app.git
git push --mirror new

Untuk masa transisi, sinkronisasi bisa dijalankan dari job terjadwal atau hook internal. Tujuannya bukan elegan, tetapi dapat diprediksi. Pastikan juga tag ikut tersalin karena banyak pipeline release bergantung pada tag.

Fase 3: Pindahkan pemicu CI sebelum memindahkan kebiasaan developer

Jika CI Anda sebenarnya berjalan di sistem eksternal, sering kali yang perlu diubah hanya sumber webhook dan status callback. Jika CI masih sangat terikat ke platform lama, pecah migrasi menjadi dua langkah:

  1. Pertahankan eksekusi CI di tempat lama, tetapi mulai uji trigger dari forge baru.
  2. Setelah stabil, pindahkan definisi pipeline atau runner ke lokasi yang lebih netral.

Prinsipnya: ubah tempat event datang dulu, lalu ubah mesin eksekusinya bila perlu. Dengan begitu, Anda bisa membedakan masalah webhook dari masalah runtime runner.

Fase 4: Cutover canonical remote

Setelah sinkronisasi repo stabil, issue penting tersedia, dan CI sudah bisa berjalan dari forge baru, baru ubah repo canonical. Pada titik ini:

  • Repo lama diubah menjadi read-only atau minimal dibatasi merge.
  • Developer mengubah remote lokal ke forge baru.
  • Bot, release, dan publish paket mulai memakai credential baru.

Sinkronisasi issue dan PR: jangan pindahkan semuanya secara buta

Untuk banyak tim, histori issue/PR lama lebih berguna sebagai arsip daripada sebagai data operasional. Karena itu, sinkronisasi selektif biasanya lebih masuk akal daripada migrasi total yang rumit.

Yang sebaiknya dipindahkan

  • Issue yang masih aktif atau masuk milestone berjalan.
  • Issue referensi untuk bug produksi yang belum selesai.
  • PR yang masih terbuka dan realistis untuk dilanjutkan.
  • Label dan milestone inti yang dipakai untuk alur kerja tim.

Yang bisa dibiarkan sebagai arsip di platform lama

  • Issue/PR yang sudah closed lama dan tidak relevan operasional.
  • Diskusi review historis yang hanya bernilai audit ringan.
  • Artefak yang tetap dapat diakses publik dan tidak memengaruhi build baru.

Jika tooling migrasi issue tidak sempurna, lebih baik pindahkan data penting beserta tautan balik ke sistem lama daripada memaksakan impor massal yang merusak relasi, penulis komentar, atau timestamp. Untuk PR terbuka, pendekatan praktisnya sering kali adalah membuat branch tetap tersedia di forge baru lalu membuka PR baru secara manual dengan referensi ke PR lama.

Perubahan remote Git di sisi developer

Begitu forge baru menjadi canonical, langkah paling terlihat bagi developer adalah perubahan remote. Buat instruksi yang singkat dan bisa disalin-tempel.

git remote -v
git remote set-url origin [email protected]:team/app.git
git fetch origin --prune
git branch -vv

Jika tim memakai beberapa remote, misalnya origin untuk fork dan upstream untuk repo utama, dokumentasikan pola baru secara eksplisit. Banyak kebingungan migrasi terjadi bukan karena Git sulit, melainkan karena setiap developer punya kebiasaan remote yang berbeda.

Hal yang perlu diverifikasi setelah ganti remote

  • git push menuju repo yang benar.
  • SSH key diterima oleh forge baru.
  • Branch tracking lokal masih menunjuk ke branch yang sesuai.
  • Hook lokal atau tool seperti pre-push tidak mengandung URL lama.

Secret management dan autentikasi: titik rawan yang sering terlambat disadari

Secret hampir selalu menjadi sumber gangguan terbesar setelah migrasi. Repository berpindah cepat, tetapi token untuk CI, registry, deploy, dan bot sering tersebar di banyak tempat.

Prinsip yang aman

  • Gunakan akun bot atau service account untuk automasi.
  • Rotasi token saat berpindah sistem, jangan menyalin token lama tanpa evaluasi.
  • Pisahkan secret per lingkungan: build, test, publish, deploy.
  • Minimalkan permission token, terutama untuk publish package dan release.

Daftar secret yang biasanya perlu ditinjau

  • SSH deploy key untuk akses repo.
  • Token API untuk membuat release atau komentar status.
  • Credential registry container atau package.
  • Credential cloud/deployment yang dibaca oleh runner.
  • Webhook signing secret jika ada validasi payload.

Jika memungkinkan, pindahkan secret sensitif ke secret manager eksternal yang tidak tergantung pada forge. Ini mengurangi penguncian vendor dan membuat migrasi berikutnya jauh lebih mudah.

Perubahan YAML CI yang biasanya diperlukan

Bagian ini sangat bergantung pada platform, jadi pendekatannya harus generik. Dalam praktiknya, perubahan YAML CI saat migrasi forge biasanya jatuh ke beberapa kategori yang berulang.

1. Trigger event berubah

Nama event untuk push, pull request, tag, atau manual dispatch bisa berbeda. Kadang yang perlu diubah bukan isi job, melainkan cara pipeline dipicu.

2. Variabel bawaan platform berubah nama

Banyak pipeline membaca variabel seperti branch name, commit SHA, actor, repository URL, atau tag release. Jangan asumsikan nama environment variable sama.

# Contoh pola netral: bungkus akses variabel platform
BRANCH_NAME="${CI_BRANCH:-${GIT_BRANCH:-unknown}}"
COMMIT_SHA="${CI_COMMIT_SHA:-${GIT_COMMIT:-unknown}}"

echo "branch=$BRANCH_NAME"
echo "commit=$COMMIT_SHA"

Pola pembungkus seperti ini memudahkan transisi karena script build tidak terlalu tergantung pada satu vendor.

3. Checkout dan fetch depth

Beberapa sistem CI melakukan shallow clone secara default. Jika pipeline release, changelog, atau versioning Anda memerlukan histori tag penuh, pastikan checkout mengambil data yang cukup.

# Contoh generik dalam shell step
git fetch --tags --force
# Bila perlu histori penuh, sesuaikan strategi checkout agar tidak shallow

4. Secret dan namespace runner berubah

Nama store untuk secret, cara injeksi environment variable, atau lokasi file credential bisa berbeda. Ini sering menyebabkan job lulus di tahap build tetapi gagal saat publish atau deploy.

5. Status check dan anotasi PR berubah

Jika tim bergantung pada komentar otomatis, anotasi test, atau status check di PR, Anda mungkin perlu adapter baru atau bot berbeda. Ini bukan sekadar kosmetik; beberapa aturan merge bergantung padanya.

6. Cache dan artefak tidak kompatibel

Jangan berasumsi cache dari sistem lama bisa dipindah begitu saja. Perlakukan hari-hari awal setelah migrasi sebagai periode cache dingin dan ukur dampaknya pada waktu build.

Contoh checklist migrasi

Checklist berikut sengaja dibuat ringkas tetapi operasional untuk tim kecil-menengah.

Sebelum migrasi

  • Inventaris repo, issue aktif, PR terbuka, webhook, runner, release, registry, auth.
  • Tentukan repo mana yang menjadi pilot project.
  • Siapkan forge baru, tim, permission, dan branch protection.
  • Buat bot account dan secret baru.
  • Uji mirror repo termasuk branch dan tag.
  • Dokumentasikan perubahan remote developer.
  • Definisikan fallback plan dan PIC on-call saat cutover.

Saat transisi

  • Aktifkan sinkronisasi repo lama ke repo baru.
  • Uji webhook ke CI dari forge baru.
  • Uji build, test, release dry-run, dan publish dry-run.
  • Pindahkan issue aktif dan PR penting secara selektif.
  • Bekukan merge singkat jika diperlukan saat verifikasi akhir.

Saat cutover

  • Ubah repo lama ke read-only atau nonaktifkan merge.
  • Jadikan repo baru sebagai canonical source.
  • Umumkan instruksi perubahan remote dan token bila relevan.
  • Validasi pipeline untuk push, branch, PR, tag, dan release.
  • Pantau log webhook, runner, dan publish registry.

Setelah cutover

  • Rotasi atau cabut token yang tidak lagi diperlukan.
  • Perbarui dokumentasi onboarding dan runbook release.
  • Tutup integrasi lama satu per satu setelah masa observasi.
  • Catat masalah aktual untuk perbaikan migrasi repo berikutnya.

Fallback plan yang realistis

Fallback plan bukan tanda Anda ragu; itu justru syarat migrasi yang matang. Untuk tim kecil-menengah, fallback yang baik harus sederhana dan bisa dijalankan tanpa improvisasi.

Pola fallback yang umum

  • Repo lama tetap read-only selama masa observasi, sehingga histori tetap tersedia.
  • Mirror balik dari forge baru ke lama untuk periode singkat bila risiko tinggi.
  • CI lama tetap siaga untuk branch utama sampai pipeline baru stabil.
  • Freeze release beberapa jam atau satu hari untuk mengurangi variabel saat cutover.

Kapan rollback diperlukan

  • Push berhasil tetapi webhook penting tidak pernah memicu CI.
  • Tag release tidak memicu publish atau menghasilkan artefak yang salah.
  • Developer kehilangan akses merge karena masalah auth/permission.
  • Registry baru gagal melayani dependency proyek lain.

Definisikan batas keputusan rollback sebelum cutover. Misalnya: jika branch utama tidak dapat dibangun dari forge baru dalam waktu tertentu, kembalikan merge ke platform lama sambil mempertahankan mirror.

Risiko umum dan cara men-debug

Webhook terkirim tetapi CI tidak jalan

Periksa payload event, secret validasi, endpoint, dan apakah event yang diaktifkan sudah benar. Banyak kegagalan terjadi karena event PR dan push dianggap setara padahal tidak.

Build jalan, publish gagal

Biasanya terkait token registry, scope paket, atau URL endpoint registry yang masih menunjuk platform lama. Audit step login dan variabel environment yang dipakai job publish.

Release otomatis tidak menemukan tag

Sering disebabkan checkout dangkal atau tag tidak ikut tersinkron. Verifikasi bahwa tag ada di repo target dan tersedia di lingkungan runner.

PR baru tidak menampilkan status check

Masalah ini sering berasal dari integrasi callback ke forge yang belum diubah. Job mungkin sukses, tetapi hasilnya tidak dilaporkan ke antarmuka PR.

Developer bisa clone tetapi tidak bisa push

Periksa SSH key yang terdaftar, permission write, branch protection, dan apakah remote benar-benar mengarah ke repo canonical.

Kriteria sukses DX tim setelah migrasi

Migrasi dianggap berhasil bukan saat repo sudah ada di tempat baru, tetapi saat developer experience tetap lancar atau membaik tanpa menambah beban operasional yang tidak perlu.

Indikator sukses yang masuk akal

  • Developer dapat clone, branch, push, dan membuka PR tanpa langkah tambahan yang membingungkan.
  • CI untuk push dan PR kembali stabil dengan kegagalan yang dapat dijelaskan.
  • Release tetap dapat dibuat dengan prosedur yang hampir sama atau lebih sederhana.
  • Issue aktif dan diskusi penting tetap mudah dilacak.
  • Tidak ada ketergantungan kritis yang masih diam-diam menunjuk ke platform lama.
  • Onboarding anggota baru tidak lebih rumit daripada sebelumnya.

Ukur keberhasilan dari gejala operasional nyata: jumlah kegagalan pipeline pasca-cutover, kebutuhan bantuan manual untuk ganti remote, insiden akses, dan waktu yang dibutuhkan untuk membuat release pertama dari forge baru.

Rekomendasi praktis untuk tim kecil-menengah

Jika Anda mempertimbangkan forge mandiri atau federatif seperti Codeberg, strategi paling sehat adalah mengurangi ketergantungan spesifik vendor sebelum hari migrasi. Simpan logika build di script repo, bukan di YAML vendor semata. Gunakan secret manager eksternal bila memungkinkan. Pisahkan CI execution dari fitur sosial forge jika kebutuhan Anda mengizinkan.

Mulailah dari satu repo pilot yang mewakili kompleksitas nyata: punya PR aktif, release, dan satu jalur publish. Jangan mulai dari repo paling sederhana jika itu membuat Anda mendapat rasa aman palsu. Setelah pilot berhasil, ulangi pola yang sama dengan checklist dan runbook yang sudah diperbaiki.

Pada akhirnya, migrasi workflow Git tim ke forge mandiri tanpa mengganggu CI adalah latihan rekayasa dependensi. Semakin jelas Anda memetakan keterkaitan repo, issue, webhook, runner, release, registry, dan auth, semakin kecil peluang developer merasakan gangguan berarti saat pindah ke forge baru.