📑 Daftar Isi
- Kenapa Custom Domain GitHub Pages Sering Gagal?
- Cara Custom Domain GitHub Pages: Step-by-Step
- Langkah 1: Pastikan Struktur Repository Kamu
- Langkah 2: Buat File CNAME di Root Repository
- Langkah 3: Aktifkan Custom Domain di Settings
- Langkah 4: Setup DNS Record di Registrar atau DNS Provider
- Langkah 5: Tunggu Propagasi dan Verifikasi DNS
- Langkah 6: Enforce HTTPS
- Troubleshooting Custom Domain GitHub Pages
- Pro Tips dari Pengalaman
- FAQ Cara Custom Domain GitHub Pages
- Q: Kenapa custom domain saya gak langsung aktif setelah di-save?
- Q: Lebih baik pakai www atau non-www?
- Q: Kok sertifikat TLS-nya gak kelar-kelar?
- Q: Apa bedanya user site dan project site buat custom domain?
- Kesimpulan
Panduan Lengkap Cara Custom Domain GitHub Pages: Step-by-Step dari CNAME sampai Enforce HTTPS
Jadi gini, kemarin ada temenku yang lagi pusing tujuh keliling gara-gara custom domain di GitHub Pages-nya gak mau aktif. Dia udah masuk ke Settings, udah isi kolom Custom domain, udah pencet Save, eh taunya malah dapat pesan error kayak gitu terus. Pas tak liat-liat, ternyata dia baru ngelakuin setengah dari pekerjaan. Aku ngerti banget, soalnya ini hal yang paling sering bikin bingung kalau baru pertama kali nyoba cara custom domain GitHub Pages. Makanya aku tulis panduan lengkap ini, biar kalian gak ngalamin hal yang sama kayak dia.
Nih, bayangin aja dulu. GitHub Pages itu kayak rumah kontrakan yang udah dikasih alamat gratis sama sang pemilik komplek, yaitu username.github.io. Tiap orang yang nyobain kontrakan ini dijamin dapet alamat itu tanpa ribet. Sekarang, kalau kamu pengen alamat sendiri yang lebih keren (misal contoh.com), kamu gak bisa cuma bilang ke satpam komplek, “Eh aku mau ganti alamat jadi contoh.com ya.” Gak sesimpel itu. Kamu juga harus pasang papan nama di depan rumah, terus ngurus administrasi biar tukang pos dan semua orang tahu kalau alamat barumu itu beneran nunjuk ke rumahmu. Dalam dunia server, “pasang papan nama” itu namanya file CNAME, dan “ngurus administrasi” itu namanya DNS. Dua-duanya wajib. Kurang satu, ya zonk.
Kenapa Custom Domain GitHub Pages Sering Gagal?
Masalahnya emang bukan cuma di satu tempat, dan ini yang bikin orang bingung. Di sisi GitHub, kamu wajib punya file CNAME di root repository yang isinya nama domain kamu. Di sisi DNS, kamu wajib bikin record yang ngarahin domain (atau subdomain) ke server GitHub Pages. Kalau file CNAME-nya udah ada tapi DNS-nya gak diurus, atau kebalikannya DNS udah bener tapi CNAME-nya lupa, ya hasilnya tetap error. Error yang paling sering muncul itu kayak “Domain is already assigned to another site” atau “DNS has not resolved yet”. Banyak orang yang udah merasa semuanya beres, padahal cuma keliatan beres dari satu sisi aja.
Terus ada juga yang bingung soal pilih domain apa — apakah pakai yang doang (contoh.com) atau pakai www.contoh.com juga. Tiap pilihan itu beda record DNS-nya lho. Buat domain doang, kamu butuh 4 A record sekaligus karena GitHub pakai 4 IP. Buat www, kamu cukup 1 CNAME record. Banyak yang cuma bikin satu record terus heran kok gak jalan. Ya kudu pasang empatnya, dek. Gak ada ceritanya besoknya langsung muncul. Aku pernah nemu kasus client yang record-nya udah lengkap, tapi ternyata dia pindah DNS server ke Cloudflare tanpa migrasiin record yang lama, jadi semua record-nya ikut ilang.
Dan jangan lupa faktor waktu. DNS itu punya yang namanya TTL (time to live) dan propagation — istilah gampangnya, berapa lama info alamat barumu disebar ke seluruh dunia internet. Registrar dan DNS provider yang beda-beda juga kecepatan propagasinya beda-beda. Yang sabar ya, biasanya 15 menit sampai 24 jam. Kalau kamu baru ganti DNS beberapa menit yang lalu terus panik, tarik napas dulu, cek lagi besok. Banyak kasus yang sebenernya gak ada masalah sama sekali, cuma waktunya belum nyampe. Aku udah pernah liat orang sampe ubah-ubah record gara-gara gak sabar, eh malah makin berantakan.
Terakhir, HTTPS. Setelah domain aktif, GitHub otomatis nyediain sertifikat TLS pakai Let’s Encrypt. Tapi proses provisioning-nya gak instan. Selama sertifikat belum jadi, halaman kamu bakal error “Certificate not active” atau semacamnya. Ini normal dan bakal beres sendiri dalam beberapa jam, asal DNS-nya udah bener. Nah kalau udah paham gambarannya, sekarang kita gas eksekusinya satu-satu.
Cara Custom Domain GitHub Pages: Step-by-Step
Oke, saiki kita mulai. Aku asumsikan kamu udah punya repository GitHub Pages yang jalan (entah itu user site username.github.io atau project site dari branch gh-pages) dan udah punya domain yang bisa diubah DNS-nya. Kalau dua-duanya belum punya, selesaikan dulu dua hal itu sebelum lanjut.
Langkah 1: Pastikan Struktur Repository Kamu
Untuk user site, nama repository-nya wajib persis <username>.github.io. Kalau udah punya domain username.github.io yang aktif, berarti struktur ini udah bener. Untuk project site, kamu bisa pake branch gh-pages atau folder /docs di branch utama — terserah mana yang kamu pake sekarang. Yang penting catet: semua langkah di bawah ini diterapin ke branch yang bener-bener di-publish sama GitHub Pages.
Langkah 2: Buat File CNAME di Root Repository
Ini langkah yang paling sering kelupaan. Bikin file baru di root repository (bukan di folder lain, harus persis di root) dengan nama persis CNAME — huruf besar semua, tanpa ekstensi. Isinya cuma satu baris, yaitu nama domain yang kamu mau, tanpa https:// dan tanpa slash di belakang:
contoh.comKalau kamu mau pake www, isi file CNAME-nya juga bisa jadi www.contoh.com. Tapi rekomendasi aku sih pakai yang tanpa www, biar konsisten. Terus commit dan push file itu ke repository. Setelah di-push, cek lagi di GitHub web interface kalau file-nya beneran ada dan isinya bener — kadang nulis file secara manual lewat web itu gampang ke-skip.
/docs atau branch gh-pages, pastikan file CNAME ada di situ, bukan cuma di branch source.Langkah 3: Aktifkan Custom Domain di Settings
Masuk ke repository kamu, terus buka Settings > Pages. Di bagian Custom domain, isi dengan domain yang sama persis seperti isi file CNAME tadi, terus klik Save. Kalau file CNAME-nya udah bener, kamu bakal liat pesan sukses dan muncul tanda cek. Kalau muncul error, balik lagi ke langkah 2 — hampir selalu soal file CNAME atau DNS yang belum kelar.
Btw, perhatiin juga opsi Enforce HTTPS di halaman yang sama. Jangan centang dulu sebelum DNS-nya kelar dan sertifikatnya jadi, nanti kita balik ke sini lagi di langkah 6.
Langkah 4: Setup DNS Record di Registrar atau DNS Provider
Ini bagian yang paling sering bikin kepala pusing. Tapi tenang, yang penting kamu ngerti dua skenario: pakai apex domain (contoh.com) atau pakai subdomain (www.contoh.com). Dua-duanya gak sama record-nya.
Kalau kamu pakai apex domain, kamu butuh 4 A record yang ngarah ke IP GitHub. IP-nya ini udah fixed dan resmi dari GitHub, jadi jangan diganti-ganti:
| Record | Name | Value | TTL |
|---|---|---|---|
| A | @ | 185.199.108.153 | 3600 |
| A | @ | 185.199.109.153 | 3600 |
| A | @ | 185.199.110.153 | 3600 |
| A | @ | 185.199.111.153 | 3600 |
| AAAA | @ | 2606:50c0:8000::153 | 3600 |
| AAAA | @ | 2606:50c0:8001::153 | 3600 |
| AAAA | @ | 2606:50c0:8002::153 | 3600 |
| AAAA | @ | 2606:50c0:8003::153 | 3600 |
Buat yang pakai www (subdomain), cukup satu CNAME record yang ngarah ke username.github.io (ini user site kamu, jangan lupa ganti username-nya):
| Record | Name | Value | TTL |
|---|---|---|---|
| CNAME | www | username.github.io | 3600 |
Kalau kamu pengen contoh.com dan www.contoh.com dua-duanya jalan, kamu gabung dua-duanya: 4 A record (dan 4 AAAA kalau mau support IPv6) buat apex, plus 1 CNAME buat www. Ini kombinasi yang paling umum dan paling rapi.
www yang lama ngarah ke hosting lain), kamu wajib hapus atau ganti dulu. Satu nama record gak bisa punya dua target yang beda-beda. Selain itu, kalau di registrar kamu ada fitur “domain forwarding” yang aktif, matiin dulu — dia bakal berantem sama redirect bawaan GitHub.Langkah 5: Tunggu Propagasi dan Verifikasi DNS
Setelah record-nya dipasang, kamu gak bisa langsung santai dulu. DNS butuh waktu buat nyebar. Buat mastiin record-nya udah bener, cek pake dig atau nslookup dari terminal kamu:
dig contoh.com +shortHasil yang diharapkan kalau domain apex: harus muncul 4 IP GitHub di atas. Kalau muncul IP lain, berarti record A-nya salah atau masih ke-cache. Buat subdomain www:
dig www.contoh.com +shortIni harus ngasih output username.github.io. Kalau dua-duanya udah sesuai, berarti DNS-nya udah bener dan tinggal nunggu GitHub nge-provision sertifikat TLS. Oh ya, satu catatan: TTL 3600 artinya setelah kamu ubah record, perubahan itu butuh waktu maksimal 1 jam buat tersebar ke semua resolver. Sabar ya.
Langkah 6: Enforce HTTPS
Balik lagi ke Settings > Pages. Setelah domain aktif dan DNS resolve, GitHub bakal mulai bikin sertifikat TLS otomatis (pakai Let’s Encrypt). Tunggu beberapa menit sampai beberapa jam sampai statusnya jadi aktif, baru centang opsi Enforce HTTPS. Kalau kamu centang terlalu cepet pas sertifikatnya belum jadi, bisa error. Jadi urutannya: DNS kelar dulu, domain aktif, sertifikat jadi, baru enforce HTTPS.
Setelah enforce HTTPS aktif, tes akses lewat browser:
curl -I https://contoh.comKamu mau liat respons HTTP/2 200 atau 301 yang ngarah ke https. Kalau muncul cert error, berarti masih proses provisioning — cek lagi beberapa jam kemudian. Kalau masih error juga setelah 24 jam, berarti ada yang salah di DNS atau CNAME, balik ke langkah 2-4.
Troubleshooting Custom Domain GitHub Pages
Biar gak bolak-balik bingung, ini tabel troubleshooting yang aku kumpulin dari pengalaman nanganin case yang mirip-mirip. Simpen dulu ya, siapa tahu kepake.
| Gejala | Kemungkinan Penyebab | Solusi |
|---|---|---|
| “Domain is already assigned to another site” | Domain dipake di repository lain | Cek semua repository GitHub kamu, hapus custom domain yang lama |
| “DNS has not resolved yet” | Record DNS belum dipasang atau belum propagate | Cek record A/CNAME dengan dig, tunggu 24 jam |
| Sertifikat “Certificate not active” | Provisioning TLS belum selesai | Pastikan DNS resolve, tunggu beberapa jam |
| Domain aktif tapi redirect ke username.github.io | CNAME file isi atau letaknya salah | Pastikan file CNAME di root branch yang deploy |
| Halaman 404 padahal DNS bener | Repository atau branch Pages belum sesuai | Cek source Pages di Settings > Pages |
Dari tabel di atas, poin yang paling sering aku temuin di lapangan itu soal file CNAME yang letaknya salah atau isinya beda sama yang di Settings. Kadang orang isi contoh.com di Settings tapi file CNAME-nya nulis www.contoh.com. Dua-duanya harus konsisten, jadi biar aman, isi keduanya sama persis. Jangan lupa juga kalau kamu punya beberapa environment (misal staging sama production), jangan sampe file CNAME yang ke-push malah dari environment yang salah.
Pro Tips dari Pengalaman
Beberapa hal kecil yang kadang gak kepikiran, tapi dampaknya gede:
- Pakai www dan non-www secara konsisten. Pilih salah satu jadi primary, terus redirect yang satu ke yang lain. GitHub handle redirect dari www ke non-www (atau kebalikannya) otomatis, asal CNAME dan Settings kamu konsisten. Jangan biarkan dua-duanya aktif tanpa arah, karena bisa bikin user bingung dan SEO split.
- Cek DNS dengan tool online. Kalau gak ada terminal di deket kamu, bisa pakai tool DNS lookup online. Tapi yang paling penting: cek dari beberapa lokasi, karena hasil dari ISP kamu doang belum tentu mewakili seluruh dunia.
- Jangan pake DNS record yang bukan punya GitHub. Ada banyak tutorial lawas yang nulis IP lama. Empat IP 185.199.x.x di atas itu yang resmi dan dipake sampai sekarang. Kalau kamu liat tutorial yang nyebut IP beda, jangan langsung ikut.
- Ubah TTL-nya kecil dulu. Sebelum ganti record, turunin TTL ke 300 (5 menit). Ini biar kalau ada kesalahan, perubahannya cepat tersebar dan kamu gak nunggu 1 jam mulu buat testing.
Oh iya, soal DNS propagation ini juga pernah aku bahas lebih dalam. Kalau penasaran kenapa sih DNS suka lambat dan gimana cara debug-nya, cek artikel Panduan Troubleshooting DNS Propagation. Buat yang pengen paham lebih dalem soal record A dan CNAME, mampir ke Cara Setup DNS A Record. Terus kalau kamu nanti mau ngelanjutin dari GitHub Pages ke VPS beneran, baca dulu Migrasi Website ke VPS biar gak kaget bedanya.
FAQ Cara Custom Domain GitHub Pages
Q: Kenapa custom domain saya gak langsung aktif setelah di-save?
Karena ada beberapa proses yang berjalan berurutan. File CNAME harus bener, DNS record harus resolve, dan GitHub butuh waktu bikin sertifikat TLS. Masing-masing butuh waktu. Kasih toleransi 24 jam sebelum mulai panik dan mengubah-ubah record.
Q: Lebih baik pakai www atau non-www?
Gak ada yang salah secara teknis. Yang penting konsisten. Pilih salah satu sebagai primary, biarin GitHub redirect yang satu ke yang lain. Buat SEO dan branding, beberapa orang prefer non-www karena lebih pendek dan modern, tapi www juga fine. Yang jelek itu justru dua-duanya aktif tanpa konsistensi.
Q: Kok sertifikat TLS-nya gak kelar-kelar?
GitHub make Let’s Encrypt dan prosesnya bisa sampai beberapa jam. Pastikan DNS kamu udah resolve ke IP GitHub dan file CNAME-nya bener. Kalau udah 24 jam masih belum aktif, cek lagi DNS-nya dari tool eksternal — kemungkinan besar record-nya salah atau ke-cache.
Q: Apa bedanya user site dan project site buat custom domain?
Untuk user site (username.github.io), custom domain berlaku buat semua halaman di repo itu. Untuk project site, custom domain cuma berlaku di project itu, dan kamu butuh satu file CNAME per repository. Sisanya — DNS record, enforce HTTPS, TTL — cara kerjanya sama aja.
Kesimpulan
Sebenernya cara custom domain GitHub Pages itu gak ribet-ribet amat. Intinya cuma tiga hal: file CNAME yang bener, DNS record yang sesuai (4 A record buat apex atau 1 CNAME buat www), dan sabar nunggu propagation plus provisioning sertifikat. Asal tiga hal ini beres, domain kamu bakal jalan mulus. Nah, kalau kamu pengen paham lebih dalam soal cara kerja DNS dan kenapa dia suka bikin orang pusing, jangan lupa baca artikel troubleshooting DNS propagation yang udah aku tulis sebelumnya ya.
Bookmark artikel ini aja deh buat referensi nanti — karena percaya deh, custom domain ini bukan sekali jalan. Mau ganti domain, mau pindah ke VPS, mau setup SSL manual, pasti balik lagi ke urutan langkah yang sama. Simpan baik-baik, dan semoga gak ada lagi yang ngalamin pusing kayak temenku tadi. Santai aja, gak susah kok. Mugi bermanfaat, matur nuwun udah baca sampe sini.