Cara Menghubungkan Project Lokal ke Repository GitHub

Kamu baru saja membuat aplikasi Laravel dengan composer create-project laravel/laravel nama-app. Kodenya jalan di laptop, kamu puas dengan hasilnya, dan sekarang ingin menyimpannya ke GitHub supaya aman — sekaligus nanti bisa dikerjakan dari komputer lain atau diajak kolaborasi. Lalu muncul pertanyaan pertama yang langsung membingungkan: gimana caranya push project lokal ke GitHub untuk pertama kali?

Pertanyaan ini sederhana di permukaan, tapi di baliknya ada banyak jebakan yang hampir semua pemula pernah langkahi. Mungkin kamu pernah mencoba git remote add origin <url> lalu diblokir dengan fatal: remote origin already exists, atau push pertama ditolak dengan ! [rejected] ... non-fast-forward, atau muncul error: src refspec main does not match any yang tidak masuk akal sama sekali.

Artikel ini membahas dua jalur utama menghubungkan project lokal ke GitHub: menginisialisasi project lokal lalu menautkannya ke repository baru, dan men-clone repository yang sudah ada. Ditambah autentikasi push pertama (personal access token untuk HTTPS, SSH key untuk SSH), cara mengatasi error yang umum, dan praktik terbaik yang spesifik untuk project Laravel.

Memahami Dua Jalur Menghubungkan Project ke GitHub

Sebelum menjalankan perintah apa pun, ada satu keputusan yang harus kamu buat — dan inilah sumber kebingungan paling besar untuk pemula.

Menurut panduan resmi GitHub, untuk memulai repository Git ada dua pilihan: git init atau git clone — tetapi bukan keduanya. Keduanya menjawab pertanyaan yang berbeda, dan memilih yang salah akan membuat alur kerja kamu berantakan dari awal.

git init vs git clone

git init dipakai ketika project sudah ada secara lokal tapi belum pernah di-track Git sama sekali. Contoh paling pas: aplikasi Laravel hasil composer create-project yang belum punya folder .git. Di sinilah kamu memulai repository dari nol.

git clone dipakai ketika repository sudah ada di remote (GitHub) dan kamu ingin membuat salinan lokalnya untuk dikerjakan. Perintah ini otomatis menyiapkan folder .git sekaligus mengatur remote origin — kamu tidak perlu git init lagi di dalam hasil clone.

Intinya:

• Kalau kamu akan meng-upload project lokal yang sudah ada ke GitHub, pakai git init, lalu tautkan ke remote.
• Kalau repository sudah ada di GitHub dan mau dikerjakan di laptop, pakai git clone.

Kabar baiknya, bagian utama artikel ini (section 3 sampai 6) memakai jalur git init karena itu kasus yang paling sering dicari — upload project lokal yang baru dibuat ke repository GitHub yang masih kosong.

Alur Umum Menghubungkan Project Lokal

Berikut peta langkah yang akan kita jalani. Semua ini akan dibahas satu per satu:

1. Buat repository di GitHub (bisa kosong atau berisi README — ini ada konsekuensinya).
2. Inisialisasi project lokal dengan git init.
3. Buat commit pertama dengan git add dan git commit.
4. Tambahkan remote dengan git remote add origin <url>.
5. Autentikasi push pertama (PAT untuk HTTPS atau SSH key).
6. Push pertama dengan git push -u origin main.

Kedengarannya sederhana, tapi setiap langkah punya detail yang kalau terlewat bisa membuat push pertama gagal. Mari mulai dari langkah pertama.

Membuat Repository di GitHub

Buka GitHub dan klik tombol New untuk membuat repository baru. Formulirnya menawarkan beberapa pilihan: nama repository, deskripsi, visibility (Public atau Private), plus tiga opsi tambahan di bagian bawah — README, .gitignore template, dan license.

Ketiga opsi terakhir itu memang terlihat praktis, tapi hati-hati: memilihnya sekarang punya dampak besar pada push pertama kamu nanti.

Kapan Repo Dibuat Kosong

Dokumentasi resmi GitHub menyarankan hal yang mungkin terdengar kontra-intuitif: kalau kamu akan meng-upload project lokal yang sudah ada, jangan inisialisasi repository di GitHub dengan README, license, atau file .gitignore. Docs-nya berbunyi: "don't initialize the new repository with README, license, or gitignore files. You can add these files after your project has been pushed."

Mengapa? Karena README atau license dari template itu akan membentuk commit pertama di GitHub. Commit ini berbeda sejarahnya dari commit lokal kamu, sehingga saat push pertama, Git melihat dua history yang tidak saling terhubung dan menolaknya dengan error non-fast-forward. Ini akan kita bahas tuntas di section 8.

Jadi untuk sekarang: buat repository kosong, salin URL-nya, dan tambahkan README serta file lainnya setelah project berhasil di-push. Untuk project Laravel, kamu bahkan tidak perlu .gitignore template dari GitHub — Laravel sudah menyertakan file .gitignore bawaan di dalam project yang mengecualikan vendor/, node_modules/, dan lainnya. Pastikan file ini ikut ter-commit pada langkah berikutnya, supaya folder vendor (yang besar) tidak ikut di-upload.

Menginisialisasi Project Lokal

Sekarang saatnya menautkan project lokal ke Git. Buka terminal atau Git Bash di direktori root project, lalu jalankan:

git init

Perintah ini membuat folder tersembunyi .git di dalam project — inilah yang membedakan direktori biasa dengan repository Git. git init hanya dijalankan satu kali; setelahnya direktori itu sudah menjadi repository.

Menentukan Nama Branch Default

Default branch modern Git dan GitHub adalah main, bukan master — perubahan ini sudah berlaku sejak akhir 2020. Pada Git versi 2.28.0 ke atas, kamu bisa langsung menentukan nama branch saat inisialisasi:

git init -b main

Untuk Git yang lebih lama, gunakan git init diikuti dengan:

git symbolic-ref HEAD refs/heads/main

Kamu juga bisa mengubah nama branch yang sudah ada dengan git branch -M main. Nama branch ini penting — kalau branch lokal masih master sedangkan remote mengharapkan main, push pertama akan gagal dengan error refspec (section 9). Cara mengubah nama branch ini sudah kita bahas lebih dalam di artikel tentang ganti nama branch master ke main.

Mengatur Identitas Git

Sebelum membuat commit, pastikan user.name dan user.email Git sudah di-set. Kalau belum, Git akan memintanya. Atur sekali secara global:

git config --global user.name "Nama Kamu"
git config --global user.email "email@example.com"

Membuat Commit Pertama

Inisialisasi repository Git belum berarti apa-apa sampai kamu membuat commit pertama. Git baru benar-benar "mengenal" branch main setelah commit pertama dibuat. Untuk project Laravel, alur lengkapnya kira-kira seperti ini:

composer create-project laravel/laravel nama-app
cd nama-app
git init -b main
git add .
git commit -m "Initial commit: aplikasi Laravel"

git add . men-stage semua file untuk commit pertama, dan git commit -m "..." mengabadikannya. Karena Laravel membawa .gitignore bawaan, folder vendor dan node_modules otomatis tidak ikut ter-stage — periksa dengan git status kalau ragu.

Menambahkan Remote Origin

Commit pertama sudah ada. Sekarang giliran menghubungkan repository lokal dengan repository GitHub kamu.

URL remote bisa diambil dari halaman Quick Setup repository yang baru kamu buat. Salin URL-nya, lalu tambahkan sebagai remote:

git remote add origin https://github.com/USER/nama-app.git

origin hanyalah nama konvensional untuk remote utama — ia label lokal, bukan sesuatu yang istimewa di sisi GitHub. Setelah ditambahkan, verifikasi dengan:

git remote -v

Output-nya menampilkan nama remote beserta URL fetch dan push:

origin  https://github.com/USER/nama-app.git (fetch)
origin  https://github.com/USER/nama-app.git (push)

Selalu biasakan cek git remote -v setelah menambahkan remote. Ini menyelamatkan kamu dari error "origin already exists" nantinya (section 9).

HTTPS vs SSH: Memilih URL

Ada dua format URL yang bisa kamu pakai:

• HTTPS: https://github.com/USER/nama-app.git
• SSH: git@github.com:USER/nama-app.git

Perhatikan bedanya — URL SSH memakai colon setelah host, bukan slash. Kedua protokol bisa dipertukarkan dengan mengganti URL remote, tapi cara autentikasinya berbeda.

HTTPS paling mudah untuk mulai, bekerja meski di belakang firewall/proxy, dan enak dipakai di lingkungan CI. Kekurangannya: kamu perlu memasukkan kredensial saat push. SSH lebih nyaman untuk kerja rutin karena sekali di-setup, push dan pull berikutnya tidak lagi menanyakan kredensial — tapi kamu harus menyiapkan SSH key dulu. Dua-duanya akan dibahas di section berikutnya.

Autentikasi untuk Push Pertama

Inilah bagian yang paling sering bikin developer baru menyerah: saat push pertama, Git meminta kredensial — dan jawaban yang selama ini diajarkan ("masukkan password akun") sudah tidak berlaku lagi di GitHub.

Autentikasi HTTPS: Personal Access Token

GitHub telah menghapus password-based authentication untuk operasi Git. Saat Git meminta password, kamu harus memasukkan personal access token (PAT), bukan password akun. Token ini dibuat dari GitHub → Settings → Developer settings → Personal access tokens.

Ada dua jenis token: fine-grained (diawali github_pat_...) dan classic (ghp_...). Untuk keamanan, gunakan fine-grained token dengan scope yang paling kecil yang dibutuhkan — misalnya hanya izin membaca dan menulis ke repository yang kamu butuhkan.

Saat push pertama dan Git meminta password HTTPS, tempel token tersebut. Untuk menghindari diminta berulang kali, kamu bisa memasang credential helper seperti Git Credential Manager — sekali masuk, token disimpan dan dipakai untuk push berikutnya. Alternative lain yang praktis: GitHub CLI, yang bisa menangani autentikasi secara interaktif lewat gh auth login.

Satu hal yang tak boleh dilupakan: jangan pernah me-commit token ke repository. Untuk project Laravel, ini sejalan dengan aturan yang sudah ada — jangan commit file .env yang berisi secret seperti database password atau API key. GitHub bahkan punya push protection yang memblokir push berisi secret ke repository publik. Cara membersihkan file .env yang terlanjur ter-commit sudah kita bahas di artikel hapus .env dari git.

Autentikasi SSH: SSH Key

Kalau kamu memilih URL SSH, alurnya berbeda. Generate keypair di mesin lokal dengan:

ssh-keygen -t ed25519 -C "email@example.com"

Lalu tambahkan ke ssh-agent supaya passphrase tersimpan selama sesi:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Selanjutnya salin isi ~/.ssh/id_ed25519.pub dan daftarkan ke GitHub → Settings → SSH and GPG keys. Terakhir, uji koneksinya:

ssh -T git@github.com

Kalau berhasil, muncul pesan "Hi ! You've successfully authenticated". Setelah itu push dan pull berjalan tanpa prompt berulang.

Pilihan HTTPS vs SSH jadi soal kenyamanan vs setup. HTTPS cepat dimulai, SSH lebih mulus untuk pemakaian harian. Keduanya benar — selama kamu tahu konsekuensinya.

Push Pertama

Remote sudah ditambahkan, autentikasi sudah siap. Saatnya momen yang ditunggu — push pertama:

git push -u origin main

Bentuk umumnya adalah git push REMOTE-NAME BRANCH-NAME. Di sini remote-nya origin, dan branch-nya main. Kalau branch default lokal kamu bukan main, ganti nama pada perintah tersebut — atau rename dulu branch-nya dengan git branch -M main.

Makna -u / --set-upstream

Huruf -u dalam perintah di atas adalah singkatan dari --set-upstream. Fungsinya mengatur hubungan tracking antara branch lokal main dengan branch remote origin/main.

Panduan resmi GitHub menjelaskannya dengan gamblang: "When pushing a branch for the first time, this type of push will configure the relationship between the remote and your local repository so that you can use git pull and git push with no additional options in the future."

Artinya, hanya push pertama yang perlu perintah lengkap. Setelah -u, kamu cukup mengetik git push dan git pull tanpa menyebut remote atau branch lagi — Git sudah tahu tujuannya dari hubungan upstream yang tersimpan. Setelahnya, repo GitHub berisi commit lokal kamu, dan hubungan upstream bisa dilihat dengan git branch -vv.

Alternatif: Menghubungkan via Clone

Alur git init di atas cocok untuk project lokal yang belum pernah di-track. Tapi bagaimana kalau repository sudah ada di GitHub dan kamu justru mau mengerjakannya di lokal?

Gunakan git clone:

git clone https://github.com/USER/nama-app.git
cd nama-app

Perintah ini otomatis menyiapkan folder .git sekaligus mengatur remote origin. Kamu tidak perlu menjalankan git remote add — semuanya sudah beres. Untuk project Laravel, workflow-nya adalah clone dulu lalu composer install di dalamnya (.gitignore mengecualikan vendor, jadi tidak ada di repo).

git clone https://github.com/USER/nama-app.git
cd nama-app
composer install

Setelah itu kamu langsung bisa bekerja: edit file, git add, git commit, lalu git push. Karena remote dan upstream sudah diatur otomatis oleh clone, git push tanpa argumen pun berfungsi.

Ingat aturan emas dari section 1: untuk repository yang sudah ada di remote, pakai clone; untuk project lokal yang belum di-track, pakai init. Jangan pakai keduanya pada repository yang sama.

Menggabungkan Repo Lokal dengan Repo GitHub yang Sudah Ada Isinya

Kamu mungkin sudah terlanjur membuat repository di GitHub dengan README dari template — dan sekarang push pertama ditolak. Tenang, ini bisa diperbaiki.

Mengapa Push Ditolak

Ketika repository GitHub sudah berisi commit (misalnya README dari template) sedangkan project lokal punya commit sendiri, Git melihat dua history yang tidak saling terhubung. Push langsung otomatis ditolak dengan non-fast-forward.

Menarik dan Menggabungkan History

Solusinya: ambil commit remote terlebih dahulu, lalu gabungkan dengan commit lokal sebelum push.

git init -b main
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/USER/nama-app.git
git fetch origin
git merge origin/main --allow-unrelated-histories
# selesaikan konflik jika muncul
git push -u origin main

Flag --allow-unrelated-histories dibutuhkan karena kedua history memang tidak saling berkaitan — tanpa flag ini, merge atau pull akan menolak. Alternatif satu baris:

git pull origin main --allow-unrelated-histories

Jika muncul konflik, selesaikan secara manual, commit hasil merge, baru push. Kalau kamu menemui konflik merge dan bingung cara menyelesaikannya, artikel tentang git merge conflict bisa membantu.

Menghindari Masalah Sejak Awal

Semua kerumitan di atas sebenarnya bisa dihindari sejak awal. Ingat saran dari section 2: kalau kamu akan meng-upload project lokal, buat repository GitHub kosong tanpa README atau license. Dengan begitu, commit pertama di GitHub sama dengan commit lokal, dan push pertama langsung berhasil tanpa perlu merge history yang tidak berhubungan.

Satu peringatan penting: saat push ditolak, jangan langsung panik dan menjalankan git push -f. Force push menimpa history remote dan bisa menghapus pekerjaan orang lain. Pahami dulu apa yang menyebabkan penolakan sebelum memutuskan.

Mengatasi Error Umum

Berikut ringkasan error yang paling sering muncul saat push pertama beserta solusinya.

"fatal: remote origin already exists."

Penyebab: Kamu memanggil git remote add origin <url> padahal remote bernama origin sudah terdaftar.

Solusi:

• Cek dulu: git remote -v.
• Kalau hanya ingin mengganti URL: git remote set-url origin <new-url>.
• Kalau mau menambah remote kedua, pakai nama lain, misalnya git remote add backup <url>.
• Untuk reset total: git remote remove origin, lalu git remote add origin <url>.

"error: src refspec main does not match any"

Penyebab: Tidak ada branch lokal bernama main untuk di-push. Biasanya karena belum ada commit pertama (Git baru membuat branch setelah commit), atau branch lokal masih bernama master.

Solusi:

• Pastikan sudah commit: git add . lalu git commit -m "Initial commit".
• Cek nama branch: git branch --show-current.
• Kalau lokal bernama master dan ingin main: git branch -M main.
• Atau push branch yang sedang aktif: git push -u origin HEAD.

"! [rejected] ... non-fast-forward" / "failed to push some refs to"

Penyebab: History lokal tidak sinkron dengan remote — repository GitHub sudah berisi commit (misal README dari template) sedangkan project lokal punya commit berbeda.

Solusi:

git fetch origin
git merge origin/main --allow-unrelated-histories
git push -u origin main

Jangan paksa dengan git push -f kecuali kamu benar-benar paham konsekuensinya.

"could not read Username" / "could not read Password"

Penyebab: Git HTTPS meminta kredensial, tapi password-based auth di GitHub sudah dihapus — atau kamu mengetik password akun bukannya token.

Solusi:

• Masukkan username dan personal access token sebagai password (bukan password akun).
• Gunakan credential helper (Git Credential Manager) atau GitHub CLI (gh auth login).
• Alternatif: beralih ke SSH.

"remote: Repository not found" / "fatal: repository not found"

Penyebab: URL salah ketik, salah kapital (URL case-sensitive), nama repository/owner salah, atau repository bersifat private tanpa izin akses.

Solusi:

• Perbaiki URL: git remote set-url origin <correct-url>, lalu git remote -v.
• Verifikasi repository benar-benar ada (buka di browser) dan URL sesuai.
• Pastikan punya akses untuk push (PAT dengan scope yang cukup untuk repository private).

"No such file or directory"

Penyebab: Perintah dijalankan di direktori yang salah, atau URL/path remote salah ketik (termasuk karakter ganda seperti https://https://).

Solusi:

• cd ke root project yang benar terlebih dahulu.
• Periksa dan perbaiki URL remote dengan git remote set-url origin <correct-url>.
• Kalau project belum di-track, jalankan git init di folder project yang tepat.

Best Practices Menghubungkan Project ke GitHub

Beberapa kebiasaan ini menjaga pengalaman upload project lokal pertama kali tetap mulus.

Sebelum push:

• Buat repository GitHub kosong saat meng-upload project lokal yang sudah ada — ini menghindari error non-fast-forward sejak awal. Tambahkan README/license setelah push berhasil.
• Inisialisasi dengan default branch main (git init -b main), dan gunakan git branch -M main jika perlu.
• Buat commit terlebih dahulu sebelum git push — Git baru membuat branch setelah commit pertama.

Keamanan project Laravel:

• Pastikan .gitignore bawaan Laravel ikut ter-stage supaya vendor/ dan node_modules/ tidak ter-commit.
• Jangan pernah commit file .env yang berisi secret.
• Jangan commit PAT atau token apa pun; gunakan fine-grained token dengan scope terkecil.

Autentikasi dan remote:

• Pilih HTTPS (PAT + credential helper) untuk setup cepat, atau SSH untuk autentikasi tanpa prompt berulang. Jaga konsistensi.
• Verifikasi remote dengan git remote -v sebelum dan sesudah menambah/mengganti remote.
• Gunakan git push -u origin main pada push pertama untuk mengatur upstream.
• Kalau mau, GitHub CLI (gh repo create --source=. --push) bisa membuat repository sekaligus push dari project lokal dalam satu perintah.

Penutup

Menghubungkan project lokal ke GitHub sebenarnya satu alur yang lurus: inisialisasi, commit, tambah remote, lalu push. Hampir semua kebingungannya datang dari tiga hal yang mudah tertukar — kapan memakai git init vs git clone, apakah repository GitHub dibuat kosong atau berisi, dan bagaimana autentikasi push pertama bekerja.

Poin kuncinya:

• git init untuk project lokal yang sudah ada; git clone untuk repository yang sudah di GitHub. Jangan pakai keduanya.
• Buat repository GitHub kosong saat meng-upload project lokal, supaya push pertama tidak kena non-fast-forward.
• git remote add origin + git push -u origin main adalah pasangan perintah inti untuk push pertama; -u mengatur upstream agar push berikutnya tanpa argumen.
• HTTPS butuh personal access token; SSH butuh SSH key. Pilih sesuai kebutuhan, dan jangan commit secret.
• Error umum seperti non-fast-forward, src refspec, dan repository not found semuanya punya penyebab dan solusi yang jelas.

Mulai dengan repository kosong, jalankan alur git init → commit → remote → push, dan project Laravel lokal kamu akan tersimpan di GitHub dengan mulus. Setelah push pertama berhasil, kamu bisa menambahkan README dan file lainnya dengan tenang.

Pengelolaan remote juga erat kaitannya dengan cara mengganti remote repository dan cara membuat dan menghapus branch agar workflow Git mu semakin rapi.

Untuk pendalaman, dokumentasi resmi adalah rujukan terbaik: git-init, git-clone, git-remote, git-push, bab Working with Remotes di Pro Git Book, dan panduan resmi GitHub tentang mengupload kode lokal serta autentikasi ke GitHub.