Panduan Setup CI/CD Otomatis dari GitHub ke VPS dengan SCP dan PM2
Panduan lengkap dan universal membangun pipeline CI/CD menggunakan GitHub Actions dan SCP untuk mengotomatisasi deployment aplikasi backend (Node.js dan Python) ke server VPS Ubuntu.
Mengelola proses deployment secara manual dengan masuk ke terminal VPS melalui SSH setiap kali ada perubahan kode sering kali memakan waktu dan rentan terhadap kesalahan manusia (human error). Untuk membangun alur kerja pengembangan modern yang efisien, penerapan pipeline CI/CD (Continuous Integration / Continuous Deployment) menggunakan GitHub Actions merupakan solusi standar industri.
Dengan mengintegrasikan alur kerja ini, setiap kali Anda melakukan perintah git push ke repositori GitHub, GitHub Actions akan otomatis terhubung ke server VPS, mentransfer berkas proyek terbaru menggunakan protokol SCP (Secure Copy), memperbarui dependensi, dan memuat ulang proses aplikasi menggunakan PM2 tanpa downtime.
1. Prasyarat Sistem di Server VPS
Sebelum menyusun alur kerja otomatisasi di GitHub, pastikan server VPS Anda (berbasis Ubuntu atau Debian) telah memenuhi prasyarat dasar berikut:
A. Memiliki Akses SSH yang Berfungsi
Pastikan Anda dapat terhubung ke VPS melalui terminal lokal dengan otentikasi SSH Key:
ssh username@ip-vps-anda
B. Memasang Node.js, npm, dan PM2
PM2 adalah process manager tingkat produksi yang sangat andal untuk menjaga aplikasi (baik Node.js, Python, maupun biner lainnya) tetap berjalan terus-menerus di latar belakang serta otomatis menyala kembali saat server melakukan reboot:
sudo apt update
sudo apt install -y nodejs npm
sudo npm install -g pm2
C. Menyiapkan Runtime Sesuai Kebutuhan Proyek
- Untuk Proyek Node.js: Node.js dan npm sudah terpasang pada langkah sebelumnya.
- Untuk Proyek Python: Pasang Python 3,
pip, dan modulvenv:sudo apt install -y python3 python3-pip python3-venv python-is-python3
D. Menyiapkan Direktori Proyek di VPS
Buat direktori tujuan di dalam server untuk menampung berkas aplikasi Anda:
mkdir -p ~/nama-proyek-anda
2. Konfigurasi GitHub Repository Secrets
Agar GitHub Actions dapat mentransfer berkas dan mengeksekusi perintah di server secara otomatis tanpa membocorkan kredensial ke publik, Anda wajib mendaftarkan data sensitif ke dalam Encrypted Secrets di GitHub:
- Buka repositori proyek Anda di GitHub.
- Masuk ke tab Settings -> Secrets and variables -> Actions.
- Klik tombol New repository secret untuk menambahkan variabel-variabel berikut:
SERVER_HOST: Alamat IP publik VPS Anda (contoh:123.45.67.89).SERVER_USERNAME: Nama pengguna login SSH di server Anda (misalnyarootatauubuntu).SERVER_SSH_KEY: Kunci privat SSH (Private Key) yang memiliki izin akses ke VPS. (Untuk melihatnya, jalankancat ~/.ssh/id_rsadi VPS. Salin seluruh isi teks mulai dari baris-----BEGIN RSA PRIVATE KEY-----hingga-----END RSA PRIVATE KEY-----).SERVER_PORT: (Opsional) Port SSH server Anda jika tidak menggunakan port default22.- Variabel Lingkungan Tambahan: Jika aplikasi Anda memerlukan Environment Variable (seperti
DATABASE_URLatauAPI_SECRET), daftarkan juga di bagian Secrets ini.
3. Membuat Berkas Workflow GitHub Actions
Langkah berikutnya adalah mendefinisikan pipeline otomatisasi di dalam repositori lokal proyek Anda:
- Buat folder baru bernama
.github/workflows/di root proyek. - Di dalam folder tersebut, buat berkas konfigurasi bernama
deploy.yml. - Gunakan konfigurasi standar di bawah ini:
name: Deploy to Ubuntu Server
on:
push:
branches:
- main # Workflow akan terpicu otomatis setiap ada push ke branch main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
# Langkah 1: Transfer berkas ke server menggunakan SCP
- name: Copy files to Server via SCP
uses: appleboy/scp-action@v0.1.7
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USERNAME }}
key: ${{ secrets.SERVER_SSH_KEY }}
port: ${{ secrets.SERVER_PORT || 22 }}
source: "."
target: "~/nama-proyek-anda"
strip_components: 0
# Langkah 2: Eksekusi skrip pembaruan dan restart di server
- name: Deploy and Restart via SSH
uses: appleboy/ssh-action@v1.0.3
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USERNAME }}
key: ${{ secrets.SERVER_SSH_KEY }}
port: ${{ secrets.SERVER_PORT || 22 }}
script: |
cd ~/nama-proyek-anda
# --- PILIHAN A: Jika Proyek Berbasis Node.js ---
# npm install --production
# --- PILIHAN B: Jika Proyek Berbasis Python ---
# [ -d "venv" ] || python3 -m venv venv
# venv/bin/pip install --upgrade -r requirements.txt
# --- RESTART APLIKASI MENGGUNAKAN PM2 ---
# Mengecek apakah proses dengan nama 'nama-aplikasi' sudah ada di PM2
pm2 describe nama-aplikasi > /dev/null
if [ $? -eq 0 ]; then
echo "Memuat ulang aplikasi..."
pm2 reload nama-aplikasi
else
echo "Memulai aplikasi baru di PM2..."
# Untuk Node.js:
pm2 start index.js --name "nama-aplikasi"
# Atau untuk Python:
# pm2 start "venv/bin/python main.py" --name "nama-aplikasi"
fi
# Menyimpan daftar proses PM2 agar persisten setelah server reboot
pm2 save
[!TIP] Ganti
~/nama-proyek-andadannama-aplikasidengan nama direktori dan nama proses yang Anda inginkan. Pilih salah satu blok instalasi dependensi (Node.js atau Python) sesuai arsitektur proyek Anda.
4. Menjalankan Deployment Pertama
Simpan berkas deploy.yml, lalu lakukan commit dan dorong perubahan tersebut ke repositori GitHub:
git add .github/workflows/deploy.yml
git commit -m "ci: add automated deployment workflow via scp and pm2"
git push origin main
Setelah perintah push selesai:
- Buka halaman repositori Anda di situs GitHub.
- Masuk ke tab Actions.
- Anda akan melihat proses alur kerja Deploy to Ubuntu Server sedang berjalan.
- Klik pada alur kerja tersebut untuk melihat log transfer berkas dan eksekusi skrip secara langsung. Jika statusnya centang hijau, aplikasi Anda telah sukses diperbarui di VPS.
5. Praktik Terbaik dan Tips Pemeliharaan
Agar sistem deployment CI/CD Anda berjalan stabil dalam jangka panjang, terapkan beberapa tips berikut:
A. Pengelolaan Berkas Lingkungan (.env)
Jangan pernah memasukkan berkas kredensial sensitif seperti .env ke dalam repositori Git publik. Buat berkas .env langsung di dalam folder server VPS Anda (~/nama-proyek-anda/.env). Karena skrip SCP hanya menyalin berkas dari repositori, berkas .env lokal di server tidak akan tertimpa selama tidak ada file .env di Git Anda.
B. Konfigurasi Startup Otomatis PM2
Agar aplikasi Anda otomatis menyala kembali ketika server VPS mengalami restart atau maintenance dari pihak cloud provider, jalankan perintah startup generator PM2 sekali saja di server:
pm2 startup
Terminal akan memberikan satu baris perintah sudo env PATH=... yang perlu Anda salin dan jalankan kembali di terminal untuk mengunci konfigurasi sistem systemd.
C. Pemantauan dan Pengecekan Log
Jika suatu saat proses deployment di GitHub Actions berhasil namun aplikasi tidak merespons, masuklah ke server VPS Anda dan jalankan perintah berikut untuk melihat pesan galat:
pm2 status # Melihat status hidup/matinya proses
pm2 logs nama-aplikasi # Melihat log runtime aplikasi secara real-time
pm2 monit # Dashboard visual penggunaan CPU dan RAM
6. Kesimpulan
Dengan membangun pipeline otomatisasi CI/CD menggunakan GitHub Actions, SCP, dan PM2, proses rilis aplikasi kini sepenuhnya terotomatisasi. Setiap perubahan kode yang disetujui dan didorong ke branch utama akan langsung terefleksi di server produksi secara konsisten, aman, dan tanpa repot.