Daftar Periksa Penyerahan Kode Sumber untuk Klien dan Agensi

Apa yang harus dicapai oleh penyerahan kode sumber

Penyerahan kode sumber adalah momen ketika proyek berhenti menjadi “sesuatu yang dijalankan agensi” dan menjadi “sesuatu yang dimiliki klien.” Tanpa penyerahan yang jelas, masalah umum muncul cepat: aplikasi hanya bisa dibangun di satu laptop, produksi bergantung pada rahasia yang tak ada siapa pun yang tahu, atau pembaruan kecil berubah menjadi berhari-hari menebak-nebak.

Tujuan dari daftar periksa penyerahan kode sumber sederhana: setelah transfer, klien bisa membangun, menjalankan, dan menerapkan produk tanpa perlu agensi dalam keadaan siaga. Itu bukan berarti “tidak ada dukungan sama sekali.” Artinya hal-hal dasar bisa diulang dan terdokumentasi, sehingga orang berikutnya dapat melanjutkan dengan percaya diri.

Apa yang dihitung sebagai deliverable harus eksplisit. Minimal, penyerahan lengkap biasanya meliputi:

• Repositori penuh (termasuk file deployment dan skrip migrasi)
• Dokumen setup yang bekerja di mesin bersih
• Penyerahan akses (akun, izin, dan lokasi sistem)
• Runbook untuk tugas rutin (deploy, rollback, backup, log)
• Tag atau snapshot versi “dikenal baik” yang bisa direferensi oleh klien

Ruang lingkup sama pentingnya dengan isi. Beberapa penyerahan hanya mencakup satu lingkungan (misalnya produksi). Lainnya mencakup dev, staging, dan produksi dengan pengaturan dan proses terpisah. Jika Anda tidak menyebutkan lingkungan mana yang termasuk, orang akan berasumsi berbeda-beda, dan di situlah outage terjadi.

Cara praktis mendefinisikan keberhasilan adalah tes verifikasi: seseorang yang tidak membangun aplikasi dapat mengekspor kode (misalnya dari platform seperti Koder.ai), mengikuti dokumen, mengatur variabel lingkungan, menjalankan migrasi, membangun, dan menerapkan ke lingkungan yang disepakati.

Daftar periksa ini fokus pada kesiapan teknis: variabel lingkungan, rotasi rahasia, migrasi database, skrip deployment, dan verifikasi build. Ini tidak membahas ketentuan hukum, kontrak, klausul IP, atau sengketa pembayaran. Hal-hal itu juga penting, tapi sebaiknya dituangkan di perjanjian terpisah.

Sebelum mengekspor: sepakati kepemilikan dan waktu

Penyerahan yang rapi dimulai sebelum ada ekspor. Jika Anda sepakati siapa yang memiliki apa dan kapan, Anda menghindari kejutan menit terakhir seperti deployment rusak, hosting tidak dibayar, atau akses yang hilang.

Tetapkan tanggal penyerahan dan jendela freeze singkat

Pilih tanggal penyerahan dan definisikan jendela freeze (biasanya 24–72 jam) di mana hanya perbaikan darurat yang masuk. Ini menjaga kode yang diekspor dan sistem yang berjalan tetap sinkron. Jika hotfix diperlukan selama freeze, catat persis apa yang berubah dan pastikan itu termasuk dalam ekspor akhir.

Perjelas kepemilikan akun dan penagihan

Putuskan siapa yang akan memiliki DNS, hosting cloud, dan layanan berbayar setelah penyerahan. Ini bukan sekadar administrasi. Jika penagihan tetap pada kartu agensi, layanan bisa dihentikan tanpa peringatan.

Cara cepat membuatnya konkret:

• Sebutkan pemilik akun untuk DNS, hosting, dan email
• Konfirmasi siapa yang membayar setiap tagihan mulai tanggal penyerahan
• Putuskan apakah akun akan dipindahkan atau dibuat ulang atas nama klien
• Catat kontak dukungan untuk setiap penyedia

Tulis ini dalam bahasa sederhana agar kedua pihak dapat mengikutinya.

Daftar lingkungan dan di mana mereka berjalan

Sepakati lingkungan apa saja yang ada (local, staging, production) dan di mana masing-masing berjalan. Catat apakah staging adalah server terpisah, database terpisah, atau hanya flag fitur. Jika Anda menggunakan platform seperti Koder.ai, juga konfirmasikan apa yang dihosting di sana vs apa yang diharapkan berjalan di infrastruktur klien setelah ekspor.

Kumpulkan akses lebih awal

Jangan menunggu sampai hari terakhir untuk meminta akses. Pastikan orang yang tepat bisa mengakses yang mereka butuhkan: repo, CI, hosting, database, dan penyedia email.

Juga sepakati tes penerimaan akhir dan proses sign-off. Contoh: “Klien bisa membangun dari mesin bersih, menjalankan migrasi, menerapkan ke staging, dan lolos smoke test. Kemudian kedua pihak sign-off secara tertulis.”

Repo dan dokumentasi dasar yang harus disertakan

Daftar periksa penyerahan kode sumber yang baik dimulai dengan repo yang bisa dibuka dan dipahami dalam beberapa menit oleh tim baru. Konfirmasi apa yang disertakan (kode aplikasi, template konfigurasi, skrip) dan apa yang sengaja tidak disertakan (rahasia nyata, kunci privat, file besar yang digenerate). Jika sesuatu dikecualikan, sebutkan di mana file itu berada dan siapa yang memilikinya.

Pertahankan struktur yang dapat diprediksi. Tujuannya folder top-level yang jelas seperti frontend/, backend/, mobile/, infra/, scripts/, dan docs/. Jika proyek adalah monorepo, jelaskan bagaimana bagian-bagian saling berhubungan dan bagaimana menjalankan masing-masing.

README harus bisa dipakai oleh orang yang tidak membangun proyek. README harus membahas prasyarat dan jalur tercepat untuk menjalankan dev tanpa asumsi. Jangan biarkan pembaca menebak-nebak.

Yang harus didokumentasikan (minimal)

Sertakan bagian README singkat yang menjawab:

• Apa isi repo ini dan apa fungsinya (satu paragraf)
• Prasyarat dengan versi tepat (runtime, package manager, Docker jika perlu)
• Langkah start satu perintah untuk dev lokal (dan apa indikator “sukses”)
• Cara menjalankan tes dan membangun artifact produksi
• Di mana menemukan dokumen kunci: catatan arsitektur, migrasi, catatan deployment

Tambahkan catatan arsitektur sederhana dalam bahasa manusia: apa yang berkomunikasi dengan apa, dan mengapa. Diagram kecil opsional; beberapa kalimat biasanya sudah cukup. Contoh: “Frontend React memanggil API Go. API membaca dan menulis PostgreSQL. Background job berjalan sebagai worker terpisah.”

Akhirnya, sertakan changelog atau release notes yang diberi versi untuk build penyerahan. Bisa berupa CHANGELOG.md atau file “handoff release notes” singkat yang menyatakan commit/tag tepat, apa yang dikirim, dan masalah yang diketahui.

Jika kode diekspor dari platform seperti Koder.ai, catat tipe proyek yang dihasilkan (web, server, mobile), toolchain yang diharapkan (mis. React, Go, PostgreSQL, Flutter), dan versi OS/tooling yang didukung agar klien dapat mereproduksi build.

Variabel lingkungan: inventaris dan dokumentasi

Variabel lingkungan sering menjadi alasan mengapa “aplikasi bekerja” gagal segera setelah penyerahan. Daftar periksa penyerahan harus memperlakukan variabel ini sebagai bagian dari produk, bukan hal yang dilupakan.

Mulailah dengan menulis inventaris yang dapat diikuti tim baru tanpa menebak. Simpan dalam bahasa sederhana, dan sertakan contoh format nilai (bukan rahasia nyata). Jika variabel bersifat opsional, sebutkan apa yang terjadi jika hilang dan default apa yang digunakan.

Cara sederhana untuk menyajikan inventaris:

• Nama variabel, apa yang dikendalikan, dan contoh format
• Wajib vs opsional, plus perilaku default
• Di mana di-set (CI, dashboard hosting, file .env lokal)
• Lingkungan mana yang butuh nilai berbeda (dev, staging, production)
• Siapa pemilik perubahan (klien, agensi, atau bersama)

Tegaskan perbedaan khusus lingkungan dengan jelas. Misalnya, staging mungkin menunjuk ke database uji dan penyedia pembayaran sandbox, sementara produksi menggunakan layanan live. Catat juga nilai yang harus cocok antar sistem, seperti callback URL, allowed origins, atau bundle identifier aplikasi mobile.

Dokumentasikan di mana tiap nilai berada hari ini. Banyak tim membagi nilai di beberapa tempat: file .env lokal untuk dev, variabel CI untuk build, dan pengaturan hosting untuk runtime. Jika Anda menggunakan Koder.ai untuk mengekspor aplikasi, sertakan file .env.example dan catatan singkat tentang variabel mana yang harus diisi sebelum build pertama.

Terakhir, buktikan tidak ada rahasia yang tersembunyi di repo. Jangan hanya memeriksa file saat ini. Tinjau riwayat commit untuk kunci yang tidak sengaja, file .env lama, atau kredensial yang disalin di konfigurasi contoh.

Contoh konkret: frontend React + API Go mungkin memerlukan API_BASE_URL untuk web app, dan DATABASE_URL serta JWT_SIGNING_KEY untuk backend. Jika staging menggunakan domain berbeda, tuliskan kedua nilai dan di mana mengubahnya, agar tim baru tidak mengirimkan pengaturan staging ke produksi.

Rotasi rahasia: transfer aman, lalu buktikan berhasil

Penyerahan belum lengkap sampai klien mengendalikan semua kredensial yang dibutuhkan aplikasi. Itu berarti rotasi rahasia, bukan sekadar berbagi. Jika agensi (atau kontraktor sebelumnya) masih memiliki kunci yang aktif, ada pintu masuk yang tidak dapat Anda audit.

Mulailah dengan membuat inventaris lengkap. Jangan berhenti pada password database. Sertakan API key pihak ketiga, rahasia client OAuth, webhook signing secret, kunci penandatangan JWT, kredensial SMTP, kunci akses storage, dan token sementara di CI.

Berikut checklist sederhana untuk hari rotasi:

• Daftar setiap rahasia, apa yang dibuka, dan di mana saat ini disetel (file env lokal, CI, dashboard hosting, vault)
• Buat kredensial baru di bawah akun klien, dan tetapkan pemilik untuk masing-masing (orang dan inbox tim)
• Perbarui konfigurasi aplikasi untuk menggunakan nilai baru, lalu deploy ke staging atau lingkungan uji terlebih dulu
• Cabut kredensial lama segera setelah yang baru dikonfirmasi bekerja
• Tuliskan langkah rotasi agar rotasi berikutnya rutin dan cepat

Setelah rotasi, buktikan tidak ada yang rusak. Jalankan tes “user nyata” singkat, bukan hanya memeriksa log.

Fokus pada aliran yang bergantung pada rahasia:

• Login, signup, reset password, dan refresh token
• Pembayaran, pengiriman email, dan upload file
• Webhook (verifikasi signature dan penanganan retry)
• Background job atau tugas terjadwal yang memanggil API eksternal
• Aksi admin yang mengakses endpoint terprivilege

Contoh: jika Anda mengekspor proyek dari Koder.ai dan aplikasi menggunakan penyedia pembayaran serta pengiriman email, rotasi kedua kunci itu, redeploy, lalu lakukan transaksi uji kecil dan kirim email uji. Hanya setelah sukses revokasi kunci milik agensi boleh dicabut.

Akhiri dengan dokumentasi di mana rahasia akan disimpan ke depan (vault, variabel CI, atau pengaturan hosting), siapa yang dapat mengubahnya, dan bagaimana rollback aman jika rotasi menyebabkan error.

Migrasi database dan penanganan data

Penyerahan bisa terlihat “selesai” sementara database adalah bagian yang pertama rusak. Perlakukan migrasi dan data seperti produk tersendiri: versioned, dapat diulang, dan diuji.

Mulailah dengan menuliskan versi database saat ini dan di mana migrasi berada di repo. Jelaskan secara spesifik: path folder, pola penamaan, dan ID migrasi terbaru (atau timestamp). Jika memakai PostgreSQL (umum pada backend Go), catat juga ekstensi yang diperlukan.

Yang harus didokumentasikan (agar orang lain bisa menjalankannya)

Sertakan runbook singkat yang menjawab:

• Perintah mana yang menjalankan migrasi, dan urutan eksekusinya (create database, apply migrations, lalu seeds)
• Perbedaannya per lingkungan (local, staging, production), termasuk flag “safe mode” jika ada
• Apakah migrasi otomatis saat deploy atau harus dijalankan manual, dan siapa yang diperbolehkan menjalankannya
• Strategi seed data: tidak ada, demo-only, atau record minimal yang dibutuhkan (admin user, default settings)
• Rencana rollback: apa yang bisa dibalik, dan apa yang tidak (mis. penghapusan kolom yang merusak)

Rollback harus jujur. Beberapa perubahan hanya bisa dibalik dengan restore backup. Tuliskan itu secara jelas, dan padukan dengan langkah backup (snapshot sebelum deploy, verifikasi proses restore).

Sebelum penyerahan selesai, jalankan migrasi pada salinan data produksi jika memungkinkan. Ini menangkap query lambat, indeks yang hilang, dan masalah “bekerja pada data kosong.” Tes realistis: ekspor kode, atur variabel lingkungan, pulihkan dump yang dianonimkan, lalu terapkan migrasi dari awal. Latihan ini memvalidasi sebagian besar aspek teknis penyerahan.

Jika aplikasi dibuat di platform seperti Koder.ai lalu diekspor, periksa lagi bahwa file migrasi dan skrip seed termasuk dalam ekspor dan masih direferensikan dengan benar oleh proses startup backend.

Build dan CI: buat dapat diulang

Penyerahan hanya lengkap ketika orang lain bisa membangun aplikasi dari nol di mesin bersih. Daftar periksa harus mencantumkan perintah build tepat, versi yang dibutuhkan, dan output yang diharapkan (mis. “bundle web di /dist”, “binary API dengan nama X”, “lokasi APK Flutter”).

Tuliskan alat dan package manager yang benar-benar Anda gunakan, bukan yang Anda kira dipakai. Untuk stack umum ini mungkin Node.js (npm atau pnpm) untuk React web app, toolchain Go untuk server, alat klien PostgreSQL untuk setup lokal, dan Flutter SDK untuk mobile.

Buat instalasi dependency dapat diprediksi. Konfirmasi lockfile dikomit (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) dan lakukan instalasi bersih di komputer baru atau container untuk membuktikan bekerja.

Tangkap apa yang dilakukan CI, langkah demi langkah, agar bisa disalin ke penyedia CI lain jika perlu:

• Install dependencies (dengan lockfiles)
• Jalankan tes dan pemeriksaan lint
• Build outputs (web bundle, server binary, mobile build)
• Hasilkan artifact (zip, Docker image, release bundle)
• Simpan log dan metadata build (versi, commit, tanggal)

Pisahkan konfigurasi saat build dari konfigurasi runtime. Konfigurasi build mengubah apa yang dikompilasi (mis. API base URL yang dibake ke bundle web). Konfigurasi runtime disuntikkan saat aplikasi mulai (mis. database URL, API key, feature flag). Pencampuran ini sering membuat “bekerja di CI” tapi gagal setelah deployment.

Sediakan resep verifikasi lokal sederhana. Bahkan beberapa perintah singkat sudah cukup:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Jika Anda mengekspor dari platform seperti Koder.ai, sertakan file CI yang dihasilkan atau preset build yang dipakai selama deployment agar klien bisa mereproduksi build di luar platform.

Skrip deployment dan proses rilis

Daftar periksa yang baik tidak berhenti pada “ini repo-nya.” Ia juga menjelaskan bagaimana kode menjadi layanan yang berjalan, dan siapa yang menekan tombol.

Mulailah dengan menuliskan bagaimana deployment dilakukan saat ini: manual penuh (seseorang menjalankan perintah di server), CI-driven (pipeline build dan deploy), atau via platform hosting. Sertakan di mana konfigurasi disimpan, dan lingkungan apa saja yang ada (dev, staging, production).

Buat langkah rilis dapat diulang. Jika proses bergantung pada seseorang yang mengingat 12 perintah, ubah itu menjadi skrip dan catat izin yang dibutuhkan.

Yang harus disertakan dalam paket deployment

Berikan klien cukup supaya bisa deploy di hari pertama:

• Perintah build dan run (dan versi tepat Node, Go, Flutter, dll.)
• Skrip deployment (shell script, target Makefile, atau konfigurasi pipeline)
• Akses yang dibutuhkan: peran akun cloud, registry container, DNS, admin database
• Catatan setup lingkungan: di mana env var disetel dan bagaimana berbeda per lingkungan
• Penamaan rilis: tag/release dan cara mengidentifikasi apa yang sedang berjalan

Sepakati ekspektasi downtime. Jika “zero downtime” diperlukan, jelaskan apa artinya dalam praktik (blue-green, rolling deploy, jendela read-only untuk migrasi). Jika downtime bisa diterima, tentukan jendela waktu yang jelas.

Aset statis dan cache sering menjadi titik kegagalan. Catat bagaimana aset dibangun dan disajikan, kapan cache dibersihkan, dan apakah ada CDN.

Rollback yang benar-benar bisa Anda jalankan

Rollback harus resep singkat dan teruji yang terkait dengan tag atau ID rilis. Contoh: deploy tag sebelumnya, kembalikan snapshot database jika perlu, dan invalidasi cache.

Jika aplikasi dibuat di Koder.ai lalu diekspor, sebutkan snapshot terakhir yang bekerja dan versi ekspor tepat agar klien bisa mencocokkan kode dengan rilis yang berfungsi dengan cepat.

Langkah demi langkah: verifikasi build setelah ekspor

Verifikasi adalah momen ketika Anda tahu apakah penyerahan benar-benar berhasil. Tujuannya sederhana: orang baru bisa mengambil kode yang diekspor, mengaturnya, dan mendapatkan aplikasi yang sama berjalan tanpa menebak.

Sebelum mulai, catat apa yang dianggap “benar”: versi aplikasi yang berjalan, commit/tag saat ini (jika ada), dan satu atau dua layar kunci atau respons API untuk dibandingkan. Jika ekspor berasal dari platform seperti Koder.ai, catat snapshot atau timestamp ekspor agar bisa membuktikan Anda menguji keadaan terbaru.

1. Konfirmasi ekspor cocok dengan produksi: periksa riwayat commit, release notes, atau metadata build. Bandingkan string versi yang terlihat atau perilaku kecil (seperti label UI tertentu) dengan aplikasi yang berjalan.
2. Siapkan variabel lingkungan dan rahasia: buat konfigurasi lingkungan target (lokal dan staging). Gunakan inventaris env var yang disediakan dan pastikan tidak ada nilai yang hard-coded di repo.
3. Instal dependensi dan jalankan tes: lakukan instalasi bersih (tanpa node_modules/vendor yang di-cache). Jalankan unit test dan pemeriksaan lint persis seperti didokumentasikan.
4. Jalankan migrasi dan mulai lokal: jalankan database, terapkan migrasi berurutan, dan jalankan aplikasi. Konfirmasi aplikasi bisa membaca/menulis data dasar dan tidak ada migrasi yang tertunda.
5. Deploy ke staging, smoke test, lalu promosikan: deploy menggunakan skrip/pipeline yang sama yang akan dipakai di produksi. Promosikan hanya setelah staging sesuai ekspektasi.

Untuk smoke test, singkatkan dan fokus pada risiko:

• Login/out (atau buat user uji)
• Satu workflow inti end-to-end (create-edit-save)
• Satu email/webhook/payment callback jika relevan
• Penanganan error dasar (input buruk, record hilang)
• Log tidak menunjukkan crash berulang atau error terkait rahasia

Jika ada yang gagal, tangkap perintah tepat, output error, dan env var yang digunakan. Detail itu menghemat jam kerja ketika kepemilikan berpindah.

Kesalahan penyerahan yang umum dan cara menghindarinya

Cara tercepat mengubah penyerahan menjadi kebakaran adalah menganggap “kode sudah cukup.” Daftar periksa yang baik fokus pada detail kecil dan membosankan yang menentukan apakah klien benar-benar bisa menjalankan dan mengubah aplikasi tanpa Anda.

Kesalahan yang menyebabkan paling banyak masalah

Sebagian besar masalah jatuh ke beberapa pola:

• Rahasia tidak dirotasi, sehingga password agensi, API key, atau token cloud masih bekerja setelah serah terima.
• Variabel lingkungan tidak lengkap karena beberapa nilai hanya ada di pengaturan CI atau dashboard hosting, bukan di repo.
• Perubahan satu kali di produksi terlupakan, seperti hotfix cepat, edit manual DB, atau toggle konfigurasi yang diset langsung di server.
• Migrasi database berjalan lokal tapi gagal di produksi karena izin, ekstensi, atau kepemilikan skema yang hilang.
• Tidak ada rencana rollback, dan tidak ada rilis bertag (atau release note) untuk kembali jika deploy pertama bermasalah.

Cara mencegahnya (tanpa menambah minggu kerja)

Jadikan rotasi dan pembersihan akses sebagai tugas terjadwal, bukan item “kalau sempat.” Tetapkan tanggal ketika akun agensi dihapus, kunci layanan digenerasi ulang, dan klien mengonfirmasi bisa deploy hanya dengan kredensial mereka.

Untuk env var, lakukan inventaris sederhana dari tiga tempat: repo, sistem CI, dan UI hosting. Lalu validasikan dengan menjalankan build bersih dari mesin atau container baru.

Untuk migrasi, uji dengan peran database yang sama yang akan dipakai deploy produksi. Jika produksi memerlukan langkah terangkat (mis. mengaktifkan ekstensi), tuliskan dan jelaskan kepemilikannya.

Contoh realistis: setelah mengekspor proyek dari Koder.ai, klien berhasil deploy tapi background job gagal karena satu URL queue hanya disetel di dashboard hosting. Audit env var sederhana akan menangkapnya. Padukan dengan rilis bertag dan rollback terdokumentasi (mis. “redeploy tag v1.8.2 dan pulihkan snapshot terakhir”) agar tim menghindari downtime.

Daftar periksa akhir, contoh singkat, dan langkah selanjutnya

Jika Anda hanya menyimpan satu halaman dari daftar periksa ini, simpan yang ini. Tujuannya sederhana: clone bersih harus berjalan di mesin baru, dengan rahasia baru, dan database yang bisa maju dengan aman.

Pemeriksaan cepat (lakukan dari clone bersih)

Jalankan pengecekan ini di laptop yang belum pernah melihat proyek (atau di container/VM bersih). Itu cara tercepat menemukan file hilang, asumsi tersembunyi, dan kredensial lama.

• Build dari nol: install deps, jalankan tes (jika ada), dan hasilkan build rilis tanpa edit manual.
• Konfigurasi berfungsi: set variabel lingkungan yang didokumentasikan dan konfirmasi aplikasi boot dengan file konfigurasi atau setup env baru.
• Rahasia dirotasi: verifikasi aplikasi berjalan dengan kunci baru, lalu cabut kunci lama dan pastikan tidak ada yang rusak.
• Migrasi berjalan bersih: mulai dari database kosong, jalankan migrasi, lalu jalankan aplikasi dan uji satu alur dasar.
• Jalur deployment nyata: jalankan skrip deployment atau workflow CI sekali dan konfirmasi menghasilkan output yang sama.

Contoh penyerahan sederhana

Sebuah agensi menyerahkan frontend React, API Go, dan database PostgreSQL. Tim klien clone repo, menyalin .env.example ke env nyata, dan membuat kredensial baru untuk database, penyedia email, dan API pihak ketiga. Mereka menjalankan go test (atau perintah tes yang disepakati), membangun aplikasi React, menerapkan migrasi ke instance Postgres baru, dan menyalakan kedua layanan. Terakhir, mereka deploy menggunakan skrip yang didokumentasikan dan memastikan commit yang sama bisa dibangun ulang nanti.

Langkah selanjutnya

Jaga penyerahan singkat dan punya pemilik. Walkthrough 30–60 menit sering mengalahkan dokumen panjang.

• Jadwalkan walkthrough dan rekam keputusan (siapa pemilik deploy, rahasia, dan perubahan database).
• Tetapkan satu pemilik untuk akses produksi dan satu backup.
• Sepakati commit hash build penerimaan terakhir dan tagkan.
• Jika Anda membangun di Koder.ai, ekspor kode sumber, lalu gunakan snapshot dan rollback selama deploy pertama yang dijalankan klien untuk mengurangi risiko.