Cara Mengatur GitLab CI/CD untuk Menyebarkan Aplikasi Frontend ke Vercel

GitLab CI/CD adalah alat yang ampuh untuk mengotomatiskan alur kerja pengembangan dan penyebaran aplikasi Anda. Dalam panduan komprehensif ini, kami akan memandu Anda melalui proses pengaturan GitLab CI/CD untuk secara otomatis menyebarkan aplikasi frontend Anda ke Vercel, platform populer untuk hosting dan penskalaan aplikasi web. Ikuti langkah-langkah ini untuk menyederhanakan penyebaran aplikasi Anda dan pastikan pengalaman yang lancar bagi pengguna Anda.

Daftar Isi

1. Pendahuluan: Mengapa Menggunakan GitLab CI/CD dengan Vercel?
2. Prasyarat
3. Langkah 1: Membuat Proyek Vercel dan Mendapatkan Token
4. Langkah 2: Menyiapkan Proyek GitLab Anda
5. Langkah 3: Menambahkan Variabel CI/CD GitLab yang diperlukan
6. Langkah 4: Membuat File `.gitlab-ci.yml`
7. Langkah 5: Menguji Alur CI/CD Anda
8. Langkah 6: Mengonfigurasi Cabang Penyebaran (Opsional)
9. Langkah 7: Mengoptimalkan Alur CI/CD Anda
10. Penyelesaian Masalah Umum
11. Praktik Terbaik untuk GitLab CI/CD dan Penyebaran Vercel
12. Kesimpulan

1. Pendahuluan: Mengapa Menggunakan GitLab CI/CD dengan Vercel?

Integrasi GitLab CI/CD dengan Vercel menawarkan banyak keuntungan untuk pengembangan aplikasi frontend. Berikut adalah beberapa alasan kuat untuk mempertimbangkan pendekatan ini:

• Otomatisasi: Otomatiskan proses penyebaran Anda, mengurangi upaya manual dan potensi kesalahan manusia.
• Kecepatan: Sebarkan aplikasi Anda dengan cepat dan efisien setiap kali perubahan didorong ke repositori Anda.
• Konsistensi: Pastikan bahwa setiap penyebaran konsisten dan mengikuti proses standar.
• Kolaborasi: Memungkinkan tim Anda berkolaborasi lebih efektif dengan merampingkan alur penyebaran.
• Kembali: Otomatiskan pengembalian dengan konfigurasi dan skrip yang tepat.
• Pengujian: Integrasikan pengujian otomatis ke dalam alur kerja CI/CD Anda untuk menangkap masalah lebih awal.
• Skalabilitas: Manfaatkan infrastruktur dan penskalaan Vercel yang andal untuk aplikasi Anda.

2. Prasyarat

Sebelum Anda memulai, pastikan Anda memiliki yang berikut ini:

• Akun GitLab: Anda memerlukan akun GitLab dengan akses ke repositori tempat kode aplikasi frontend Anda disimpan.
• Akun Vercel: Anda memerlukan akun Vercel dengan akses ke proyek tempat Anda ingin menyebarkan aplikasi Anda.
• Aplikasi Frontend: Anda harus memiliki aplikasi frontend yang berfungsi yang siap disebarkan (misalnya, React, Vue, Angular, atau situs statis).
• Node.js dan npm (atau Yarn): Diperlukan untuk menjalankan perintah build secara lokal dan untuk beberapa skrip.

3. Langkah 1: Membuat Proyek Vercel dan Mendapatkan Token

Pertama, Anda perlu membuat proyek Vercel untuk aplikasi frontend Anda. Jika Anda sudah memiliki proyek, Anda dapat melewati langkah ini.

1. Buat Proyek Vercel:
• Masuk ke akun Vercel Anda di vercel.com.
• Klik tombol “Add New Project”.
• Pilih repositori Git Anda (GitLab) dari daftar penyedia.
• Izinkan Vercel untuk mengakses repositori GitLab Anda jika diminta.
• Konfigurasikan proyek Anda dengan pengaturan yang tepat untuk aplikasi frontend Anda (misalnya, perintah build, direktori output).
• Klik “Deploy” untuk membuat proyek Vercel Anda.
2. Dapatkan Token Vercel Anda:
• Di Vercel, buka pengaturan akun Anda.
• Navigasi ke bagian “Tokens”.
• Buat token baru dengan deskripsi yang bermakna (misalnya, “GitLab CI/CD Token”).
• Salin token yang dihasilkan. Anda akan memerlukan ini di GitLab. Simpan token ini dengan aman.

4. Langkah 2: Menyiapkan Proyek GitLab Anda

Selanjutnya, siapkan proyek GitLab Anda untuk integrasi CI/CD.

1. Akses Proyek GitLab Anda:
• Buka proyek GitLab Anda melalui antarmuka web GitLab.
2. Pastikan `.gitignore` yang benar:
• Pastikan file `.gitignore` Anda menyertakan direktori `node_modules` dan file build lainnya yang tidak boleh dilacak oleh Git. Contoh `.gitignore`:

  node_modules
  .next
  dist
  build
  

5. Langkah 3: Menambahkan Variabel CI/CD GitLab yang Diperlukan

Untuk mengautentikasi dengan Vercel dari GitLab CI/CD, Anda perlu menambahkan variabel CI/CD ke proyek GitLab Anda.

1. Navigasi ke Variabel CI/CD:
• Di proyek GitLab Anda, buka “Settings” -> “CI/CD”.
• Perluas bagian “Variables”.
• Klik “Add variable”.
2. Tambahkan Variabel:
• Tambahkan variabel berikut:
  • VERCEL_TOKEN: Setel ini ke token Vercel yang Anda dapatkan di Langkah 1.
  • VERCEL_ORG_ID: Setel ini ke ID organisasi Vercel Anda. Anda dapat menemukannya di pengaturan akun Vercel Anda atau di URL dasbor proyek Anda.
  • VERCEL_PROJECT_ID: Setel ini ke ID proyek Vercel Anda. Anda dapat menemukannya di pengaturan proyek Vercel Anda atau di URL dasbor proyek Anda.
3. Konfigurasikan Opsi Variabel:
• Untuk setiap variabel, pertimbangkan pengaturan berikut:
  • Protected: Aktifkan ini jika Anda hanya ingin variabel tersedia untuk cabang dan tag yang dilindungi.
  • Masked: Aktifkan ini untuk mencegah variabel ditampilkan dalam log CI/CD. Sangat disarankan untuk VERCEL_TOKEN.
4. Simpan Variabel:
• Klik “Add variable” untuk menyimpan setiap variabel.

6. Langkah 4: Membuat File `.gitlab-ci.yml`

File `.gitlab-ci.yml` adalah inti dari alur kerja CI/CD Anda. Ini mendefinisikan tahapan dan pekerjaan yang akan dijalankan oleh GitLab setiap kali ada perubahan didorong ke repositori Anda. Buat file ini di root proyek Anda.

1. Buat File `.gitlab-ci.yml`:
• Di root proyek GitLab Anda, buat file bernama `.gitlab-ci.yml`.
2. Definisikan Tahapan:
• Tentukan tahapan yang ingin Anda sertakan dalam alur kerja Anda. Tahap umum meliputi:
  • build: Untuk membangun aplikasi frontend Anda.
  • test: Untuk menjalankan pengujian otomatis.
  • deploy: Untuk menyebarkan aplikasi Anda ke Vercel.
3. Tentukan Pekerjaan:
• Tentukan pekerjaan untuk setiap tahapan. Setiap pekerjaan menentukan serangkaian perintah yang dijalankan dalam lingkungan Docker.
4. Contoh File `.gitlab-ci.yml`:

Berikut adalah contoh file `.gitlab-ci.yml` yang menunjukkan alur kerja penyebaran dasar ke Vercel:

stages:
  - build
  - test
  - deploy

build:
  image: node:16
  stage: build
  cache:
    key: ${CI_COMMIT_REF_SLUG}-node-modules
    paths:
      - node_modules/
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/ # Atau direktori build Anda
    expire_in: 1 day

test:
  image: node:16
  stage: test
  cache:
    key: ${CI_COMMIT_REF_SLUG}-node-modules
    paths:
      - node_modules/
  script:
    - npm install
    - npm run test # Atau perintah pengujian Anda
  dependencies:
    - build

deploy:
  image: node:16
  stage: deploy
  dependencies:
    - build
  script:
    - npm install -g vercel
    - vercel deploy --prebuilt --prod --token $VERCEL_TOKEN --org $VERCEL_ORG_ID --project $VERCEL_PROJECT_ID
  environment:
    name: production
    url: https://your-vercel-app.vercel.app # Ganti dengan URL aplikasi Vercel Anda
  only:
    - main # Atau cabang utama Anda

5. Penjelasan:
• stages: Mendefinisikan urutan tahapan yang akan dijalankan.
• build:
  • image: Menggunakan gambar Docker Node.js untuk membangun aplikasi.
  • cache: Caches direktori `node_modules` untuk mempercepat build di masa mendatang.
  • script: Menginstal dependensi dan menjalankan perintah build.
  • artifacts: Upload direktori build (misalnya, `dist/`) sebagai artefak, sehingga dapat diakses oleh pekerjaan di masa mendatang.
• test:
  • image: Menggunakan gambar Docker Node.js untuk menjalankan pengujian.
  • cache: Caches direktori `node_modules` untuk mempercepat pengujian di masa mendatang.
  • script: Menginstal dependensi dan menjalankan perintah pengujian.
  • dependencies: Menentukan bahwa pekerjaan ini bergantung pada pekerjaan `build` dan akan dijalankan setelahnya.
• deploy:
  • image: Menggunakan gambar Docker Node.js untuk menyebarkan aplikasi.
  • dependencies: Menentukan bahwa pekerjaan ini bergantung pada pekerjaan `build`.
  • script:
    • Menginstal klien Vercel CLI secara global.
    • Menjalankan perintah `vercel deploy` dengan bendera berikut:
      • --prebuilt: Menentukan bahwa kita menyebarkan direktori build yang sudah ada.
      • --prod: Menyebarkan ke lingkungan produksi.
      • --token: Menggunakan token Vercel yang disimpan sebagai variabel CI/CD.
      • --org: Menggunakan ID organisasi Vercel yang disimpan sebagai variabel CI/CD.
      • --project: Menggunakan ID proyek Vercel yang disimpan sebagai variabel CI/CD.
  • environment: Menentukan nama dan URL lingkungan.
  • only: Menentukan bahwa pekerjaan ini hanya akan dijalankan untuk cabang `main`.
6. Sesuaikan File `.gitlab-ci.yml`:
• Sesuaikan file `.gitlab-ci.yml` untuk mencerminkan kebutuhan spesifik aplikasi frontend Anda. Sesuaikan perintah build, perintah pengujian, dan direktori output sesuai dengan proyek Anda.
• Ganti `https://your-vercel-app.vercel.app` dengan URL aplikasi Vercel Anda.
• Ubah `main` agar sesuai dengan cabang utama Anda (misalnya, `main`, `master`).

7. Langkah 5: Menguji Alur CI/CD Anda

Setelah Anda mengonfigurasi file `.gitlab-ci.yml`, penting untuk menguji alur CI/CD Anda untuk memastikan bahwa itu berfungsi dengan benar.

1. Dorong Perubahan ke GitLab:
• Dorong file `.gitlab-ci.yml` dan kode aplikasi Anda ke repositori GitLab Anda.
2. Pantau Alur CI/CD:
• Di proyek GitLab Anda, buka “CI/CD” -> “Pipelines”.
• Pantau alur untuk melihat apakah berhasil atau gagal.
3. Troubleshoot Kesalahan:
• Jika alur gagal, periksa log untuk setiap pekerjaan untuk mengidentifikasi penyebab kesalahan.
• Kesalahan umum meliputi:
  • Kesalahan perintah build.
  • Kegagalan pengujian.
  • Masalah otentikasi dengan Vercel.
  • Konfigurasi yang salah dalam file `.gitlab-ci.yml`.
• Perbaiki kesalahan dan dorong perubahan baru ke GitLab untuk memicu alur lain.
4. Verifikasi Penyebaran Vercel:
• Setelah alur berhasil, verifikasi bahwa aplikasi Anda berhasil disebarkan ke Vercel.
• Buka URL aplikasi Vercel Anda di browser web untuk memastikan bahwa itu berfungsi seperti yang diharapkan.

8. Langkah 6: Mengonfigurasi Cabang Penyebaran (Opsional)

Anda dapat mengonfigurasi alur CI/CD Anda untuk menyebarkan cabang yang berbeda ke lingkungan Vercel yang berbeda. Ini dapat berguna untuk penyebaran pengembangan, pementasan, dan produksi.

1. Buat Proyek Vercel Terpisah (Opsional):
• Untuk setiap lingkungan yang ingin Anda sebarkan, pertimbangkan untuk membuat proyek Vercel terpisah. Ini memungkinkan Anda untuk memiliki pengaturan konfigurasi dan domain yang berbeda untuk setiap lingkungan.
2. Tambahkan Variabel CI/CD Tambahan (Opsional):
• Jika Anda menggunakan proyek Vercel terpisah untuk setiap lingkungan, tambahkan variabel CI/CD tambahan untuk menyimpan ID proyek dan token Vercel untuk setiap lingkungan. Misalnya:
  • VERCEL_TOKEN_STAGING: Token Vercel untuk lingkungan pementasan.
  • VERCEL_PROJECT_ID_STAGING: ID proyek Vercel untuk lingkungan pementasan.
3. Modifikasi File `.gitlab-ci.yml`:
• Modifikasi file `.gitlab-ci.yml` untuk menggunakan variabel yang benar berdasarkan cabang yang sedang disebarkan. Anda dapat menggunakan kata kunci `only` dan `variables` untuk mencapai ini. Berikut adalah contoh:

  deploy_staging:
    image: node:16
    stage: deploy
    dependencies:
      - build
    script:
      - npm install -g vercel
      - vercel deploy --prebuilt --token $VERCEL_TOKEN_STAGING --org $VERCEL_ORG_ID --project $VERCEL_PROJECT_ID_STAGING
    environment:
      name: staging
      url: https://your-vercel-staging-app.vercel.app
    only:
      - staging
  
  deploy_production:
    image: node:16
    stage: deploy
    dependencies:
      - build
    script:
      - npm install -g vercel
      - vercel deploy --prebuilt --prod --token $VERCEL_TOKEN --org $VERCEL_ORG_ID --project $VERCEL_PROJECT_ID
    environment:
      name: production
      url: https://your-vercel-app.vercel.app
    only:
      - main
  

4. Penjelasan:
• Contoh ini mendefinisikan dua pekerjaan penyebaran terpisah: `deploy_staging` dan `deploy_production`.
• Pekerjaan `deploy_staging` hanya dijalankan untuk cabang `staging` dan menggunakan variabel `VERCEL_TOKEN_STAGING` dan `VERCEL_PROJECT_ID_STAGING`.
• Pekerjaan `deploy_production` hanya dijalankan untuk cabang `main` dan menggunakan variabel `VERCEL_TOKEN` dan `VERCEL_PROJECT_ID`.
• Anda dapat memperluas pola ini untuk mendukung lingkungan lain sesuai kebutuhan.

9. Langkah 7: Mengoptimalkan Alur CI/CD Anda

Ada beberapa cara untuk mengoptimalkan alur CI/CD Anda untuk kinerja dan efisiensi yang lebih baik.

1. Gunakan Caching:
• Seperti yang ditunjukkan dalam contoh file `.gitlab-ci.yml`, gunakan caching untuk menyimpan dependensi dan artefak di antara pekerjaan. Ini dapat secara signifikan mengurangi waktu build.
2. Gunakan Gambar Docker Paralel:
• Pertimbangkan untuk menggunakan gambar Docker paralel untuk menjalankan pekerjaan secara bersamaan. Ini dapat mempercepat alur CI/CD Anda secara keseluruhan.
3. Optimalkan Perintah Build Anda:
• Optimalkan perintah build Anda untuk mengurangi waktu build. Misalnya, gunakan bendera produksi untuk mengaktifkan optimasi selama proses build.
4. Gunakan Docker Layer Caching:
• Jika Anda menggunakan gambar Docker khusus, manfaatkan caching layer Docker untuk mempercepat build gambar.
5. Jalankan Pengujian Secara Paralel:
• Jika Anda memiliki banyak pengujian, jalankan secara paralel untuk mengurangi waktu pengujian.
6. Gunakan CI/CD Linting Tools:
• Gunakan alat linting CI/CD untuk memvalidasi file `.gitlab-ci.yml` Anda dan memastikan bahwa mereka bebas dari kesalahan.

10. Penyelesaian Masalah Umum

Berikut adalah beberapa masalah umum yang mungkin Anda temui saat menyiapkan GitLab CI/CD untuk penyebaran Vercel dan cara memecahkannya:

• Masalah Otentikasi:
• Pastikan bahwa token Vercel, ID organisasi, dan ID proyek yang Anda berikan di variabel CI/CD sudah benar.
• Periksa apakah token Vercel belum kedaluwarsa atau dicabut.
• Pastikan bahwa akun Vercel Anda memiliki izin yang diperlukan untuk menyebarkan proyek.
• Kesalahan Perintah Build:
• Periksa log untuk pekerjaan build untuk mengidentifikasi penyebab kesalahan.
• Pastikan bahwa perintah build sudah benar dan bahwa semua dependensi yang diperlukan diinstal.
• Coba jalankan perintah build secara lokal untuk memecahkan masalah lebih lanjut.
• Kegagalan Pengujian:
• Periksa log untuk pekerjaan pengujian untuk mengidentifikasi penyebab kegagalan.
• Pastikan bahwa perintah pengujian sudah benar dan bahwa semua dependensi yang diperlukan diinstal.
• Coba jalankan pengujian secara lokal untuk memecahkan masalah lebih lanjut.
• Masalah Penyebaran:
• Periksa log untuk pekerjaan penyebaran untuk mengidentifikasi penyebab masalah penyebaran.
• Pastikan bahwa direktori build sudah benar dan bahwa berisi semua file yang diperlukan.
• Pastikan bahwa Vercel dapat mengakses repositori GitLab Anda.
• Masalah Cache:
• Jika Anda mengalami masalah dengan caching, coba hapus cache dan jalankan alur lagi.
• Pastikan bahwa cache dikonfigurasi dengan benar dan bahwa itu menyimpan artefak yang benar.

11. Praktik Terbaik untuk GitLab CI/CD dan Penyebaran Vercel

Berikut adalah beberapa praktik terbaik untuk menggunakan GitLab CI/CD dengan Vercel:

• Gunakan Variabel Lingkungan:
• Gunakan variabel lingkungan untuk menyimpan informasi sensitif seperti token Vercel dan kredensial API.
• Gunakan Kontrol Versi:
• Gunakan kontrol versi untuk melacak perubahan pada file `.gitlab-ci.yml` dan kode aplikasi Anda.
• Gunakan Cabang:
• Gunakan cabang untuk mengelola lingkungan penyebaran yang berbeda.
• Otomatiskan Pengujian:
• Otomatiskan pengujian Anda untuk memastikan bahwa kode Anda berkualitas tinggi.
• Pantau Alur:
• Pantau alur CI/CD Anda untuk mengidentifikasi dan menyelesaikan masalah dengan cepat.
• Gunakan Tinjauan Kode:
• Gunakan tinjauan kode untuk memastikan bahwa file `.gitlab-ci.yml` dan kode aplikasi Anda berkualitas tinggi.
• Dokumentasikan Alur Anda:
• Dokumentasikan alur CI/CD Anda untuk membuatnya lebih mudah dipahami dan dipelihara.
• Keamanan:
• Selalu praktikkan keamanan yang baik. Jangan pernah menyimpan kredensial secara langsung dalam kode Anda. Gunakan variabel lingkungan dan alat manajemen rahasia.

12. Kesimpulan

Mengatur GitLab CI/CD untuk menyebarkan aplikasi frontend Anda ke Vercel dapat secara signifikan merampingkan alur kerja pengembangan dan penyebaran Anda. Dengan mengotomatiskan proses, Anda dapat memastikan penyebaran yang konsisten, mengurangi kesalahan manual, dan mempercepat rilis aplikasi Anda. Panduan ini menyediakan panduan langkah demi langkah untuk membantu Anda menyiapkan integrasi ini, mulai dari membuat proyek Vercel hingga mengoptimalkan alur CI/CD Anda. Dengan mengikuti praktik terbaik dan memecahkan masalah umum, Anda dapat memanfaatkan kekuatan GitLab CI/CD dan Vercel untuk memberikan pengalaman pengguna yang luar biasa.