Integrasi CI/CD

Mengintegrasikan Capgo ke dalam pipeline CI/CD Anda memungkinkan otomasi penuh proses build dan deployment update aplikasi. Dengan memanfaatkan Capgo CLI dan semantic-release, Anda dapat memastikan deployment yang konsisten dan andal, serta mempercepat iterasi.

Keuntungan Integrasi CI/CD

• Otomatisasi: Tidak ada lagi langkah manual atau celah untuk human error. Seluruh proses build, test, dan deployment Anda bisa diotomatisasi dari awal sampai akhir.

• Konsistensi: Setiap deployment mengikuti rangkaian langkah yang sama, sehingga prosesnya dapat diprediksi dan diulang. Ini sangat berguna saat banyak anggota tim berkontribusi pada code.

• Iterasi lebih cepat: Dengan deployment otomatis, Anda bisa merilis update lebih sering dan lebih percaya diri. Tidak perlu lagi menunggu QA manual atau persetujuan rilis.

Capgo CLI

Capgo CLI adalah kunci untuk mengintegrasikan Capgo ke dalam workflow CI/CD Anda. Di sini tersedia perintah untuk push versi bundle baru, mengelola channel, dan lainnya.

Perintah paling penting untuk integrasi CI/CD adalah bundle upload:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY

Jika Anda menggunakan enkripsi, Anda harus menyediakannya melalui salah satu cara berikut:

Menggunakan path file private key:

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-v2 PRIVATE_KEY_PATH

Menggunakan konten private key secara langsung (disarankan untuk CI/CD):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 PRIVATE_KEY_CONTENT

Menggunakan environment variables (best practice untuk CI/CD):

npx @capgo/cli@latest bundle upload --channel Production --apikey YOUR_API_KEY --key-data-v2 "$CAPGO_PRIVATE_KEY"

Mengatur Environment Variables untuk Enkripsi

Untuk lingkungan CI/CD, disarankan untuk menyimpan private key Anda sebagai environment variable, bukan sebagai file. Berikut cara mengaturnya:

1. Dapatkan konten private key Anda:

   cat .capgo_key_v2 | pbcopy

   Ini menyalin konten key ke clipboard Anda.

2. Tambahkan ke lingkungan CI/CD Anda:

   • Aksi GitHub: Tambahkan CAPGO_PRIVATE_KEY ke secrets repository Anda
   • GitLab CI: Tambahkan sebagai variabel tersembunyi di pengaturan proyek Anda
   • CircleCI: Tambahkan sebagai variabel lingkungan di pengaturan proyek Anda
   • Jenkins: Tambahkan sebagai kredensial teks rahasia

3. Gunakan di pipeline Anda:

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Catatan: --key-data-v2 flag memungkinkan Anda meneruskan konten private key langsung sebagai string, menjadikannya sempurna untuk variabel lingkungan di pipeline CI/CD di mana Anda tidak ingin membuat file sementara.

Perintah ini mengunggah build web saat ini ke channel yang ditentukan. Anda biasanya menjalankan ini sebagai langkah terakhir di pipeline CI/CD Anda, setelah build web berhasil diselesaikan.

Mengatur Capgo di Pipeline CI/CD Anda

Meskipun langkah-langkah pastinya akan berbeda tergantung pada alat CI/CD yang Anda pilih, proses umum untuk mengintegrasikan Capgo adalah sebagai berikut:

1. Buat kunci API: Masuk ke dashboard Capgo dan buat kunci API baru. Kunci ini akan digunakan untuk autentikasi CLI di lingkungan CI/CD Anda. Jaga kerahasiaannya dan jangan pernah commit ke repository Anda!

2. Konfigurasikan bundle upload perintah: Tambahkan langkah ke konfigurasi CI/CD Anda yang menjalankan bundle upload perintah dengan argumen yang sesuai:

   upload.yml

   - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

   Ganti Production dengan channel yang ingin Anda deploy ke sana, ${{ secrets.CAPGO_API_KEY }} dengan environment variable yang menyimpan API key Anda, dan tambahkan --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" jika menggunakan enkripsi.

3. Tambahkan upload setelah web build Anda: Pastikan bahwa upload step dilakukan setelah web build Anda selesai dengan sukses. Ini memastikan Anda selalu deploying code terbaru Anda. Berikut adalah contoh konfigurasi untuk GitHub Actions:

   upload.yml

   name: Deploy to Capgo
    on:
     push:
      branches: [main]
   
   jobs:
    deploy:
    runs-on: ubuntu-latest
   
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-node@v6
     with:
      node-version: '24'
   
    - run: npm ci
    - run: npm run build
   
    - run: npm install -g @capgo/cli
    - run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }} --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}"

Manajemen Versi dengan Semantic-release

Cara yang direkomendasikan untuk menangani versioning dengan Capgo adalah dengan mengatur versi di capacitor.config.ts file dengan mengimpornya dari package.json:

import pkg from './package.json'

const config: CapacitorConfig = {
  // ... other config
  plugins: {
    CapacitorUpdater: {
      version: pkg.version,
    }
  }
}

Pendekatan ini memungkinkan Anda untuk:

1. Gunakan semantic-release (atau tool lain) untuk memperbarui package.json versi
2. Build app Anda dengan versi yang diperbarui otomatis disertakan
3. Upload bundle dengan versi yang benar

Workflow CI/CD Anda akan terlihat seperti ini:

- run: npm ci
- run: npx semantic-release  # Updates package.json version
- run: npm run build         # Builds with new version from capacitor.config
- run: npx @capgo/cli@latest bundle upload --channel=production --apikey=${{ secrets.CAPGO_API_KEY }}

Berikut adalah contoh .releaserc file konfigurasi untuk semantic-release:

{
  "branches": [
    "main",
    {
      "name": "beta",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md", "package.json"],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

Konfigurasi ini melakukan hal berikut:

1. Menganalisis pesan commit untuk menentukan nomor versi berikutnya, sesuai spesifikasi Conventional Commits.
2. Menghasilkan release notes berdasarkan commit sejak rilis terakhir.
3. Memperbarui CHANGELOG.md file dengan release notes terbaru.
4. Memperbarui package.json versi, yang akan dibaca oleh capacitor.config Anda.
5. Melakukan commit pada CHANGELOG.md, package.json, serta file lain yang berubah, kembali ke repositori.

Pastikan untuk menjalankan semantic-release sebelum melakukan build aplikasi agar versi terbaru dari package.json termasuk dalam build Anda melalui capacitor.config.

Auto-bump saat versi lokal sudah ada di Capgo

Nama bundle harus unik (versi yang dihapus masih menempati namanya). Jika CI terus mengunggah yang sama package.json versi, upload akan gagal. Lebih baik bump package.json (misalnya dengan semantic-release). Jika tidak praktis, biarkan CLI memilih semver bebas berikutnya dari bundle yang terhubung ke channel, atau versi aplikasi remote terbaru:

npx @capgo/cli@latest bundle upload --channel=production --auto-bump
npx @capgo/cli@latest bundle upload --auto-bump major
npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
npx @capgo/cli@latest bundle upload --auto-bump metadata
npx @capgo/cli@latest bundle upload --channel=production --auto-bump ai

--auto-bump ai menggunakan Capgo Cloudflare Workers AI untuk membandingkan file bundle lokal dengan file delta Capgo/channel sebelumnya, memilih major | minor | patch | metadata, dan menampilkan alasan singkat. Jika tidak ada versi Capgo sebelumnya, AI dilewati dan bump-nya patch.

Jangan menggabungkan --auto-bump dengan --bundle / -b. Lihat bundle upload referensi untuk daftar opsi lengkapnya.

Pemecahan Masalah

Jika Anda menemui masalah dengan integrasi CI/CD Capgo Anda, berikut beberapa hal yang perlu diperiksa:

• key API: Pastikan key API Anda valid dan memiliki izin yang diperlukan. Jika menggunakan environment variable, periksa kembali apakah sudah di-set dengan benar.

• Versi CLI: Pastikan Anda menggunakan versi terbaru dari Capgo CLI. Versi lama mungkin memiliki masalah kompatibilitas atau tidak memiliki fitur tertentu.

• Artifact build: Konfirmasi bahwa web build Anda menghasilkan file output yang diharapkan. Capgo CLI membutuhkan web build yang valid untuk membuat bundle.

• Konektivitas jaringan: Pastikan lingkungan CI/CD Anda memiliki akses jaringan ke server Capgo. Masalah firewall atau proxy terkadang dapat mengganggu upload perintah.

Jika Anda masih mengalami kendala, hubungi dukungan Capgo untuk bantuan. Mereka dapat membantu memecahkan masalah pada konfigurasi spesifik Anda.

Kesimpulan

Integrasi Capgo ke dalam pipeline CI/CD Anda dengan manajemen versi yang tepat dapat sangat menyederhanakan alur kerja pengembangan Anda. Dengan mengotomatiskan deployment dan versioning melalui pendekatan capacitor.config, Anda dapat mengirim update lebih cepat dan dengan keyakinan yang lebih besar.

Pendekatan yang direkomendasikan untuk mengatur versi di file capacitor.config.ts dan menggunakan semantic-release untuk memperbarui package.json menyediakan proses deployment yang robust dan andal, sehingga Anda bisa fokus membangun fitur-fitur hebat tanpa perlu khawatir dengan langkah rilis manual.

Untuk detail lebih lanjut tentang perintah dan opsi Capgo CLI, lihat referensi CLI. Dan untuk pemahaman lebih dalam tentang konfigurasi semantic-release, lihat dokumentasi semantic-release.

Selamat deploy!

Lanjutkan dari Integrasi CI/CD

Jika Anda menggunakan Integrasi CI/CD untuk merencanakan otomatisasi CI/CD, hubungkan dengan CI/CD Capgo untuk workflow produk di Capgo CI/CD, Capgo Native Build untuk workflow produk di Capgo Native Builds, Integrasi Capgo untuk alur kerja produk di Integrasi Capgo, Integrasi GitHub Actions untuk detail implementasi di GitHub Actions Integration, dan Integrasi GitLab CI/CD untuk detail implementasi di Integrasi GitLab CI/CD.