hafis.

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 modul venv:
    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:

  1. Buka repositori proyek Anda di GitHub.
  2. Masuk ke tab Settings -> Secrets and variables -> Actions.
  3. 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 (misalnya root atau ubuntu).
  • SERVER_SSH_KEY: Kunci privat SSH (Private Key) yang memiliki izin akses ke VPS. (Untuk melihatnya, jalankan cat ~/.ssh/id_rsa di 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 default 22.
  • Variabel Lingkungan Tambahan: Jika aplikasi Anda memerlukan Environment Variable (seperti DATABASE_URL atau API_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:

  1. Buat folder baru bernama .github/workflows/ di root proyek.
  2. Di dalam folder tersebut, buat berkas konfigurasi bernama deploy.yml.
  3. 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-anda dan nama-aplikasi dengan 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:

  1. Buka halaman repositori Anda di situs GitHub.
  2. Masuk ke tab Actions.
  3. Anda akan melihat proses alur kerja Deploy to Ubuntu Server sedang berjalan.
  4. 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.