Integrasi GitLab CI/CD

Integrasikan Capgo Live Updates dengan GitLab CI/CD untuk deploy update aplikasi secara otomatis setiap kali Anda push code. Panduan ini membahas cara setup workflow build, testing, dan deployment otomatis.

Prerequisites

Sebelum mengatur integrasi GitLab CI/CD, pastikan Anda sudah memiliki:

• Akun GitLab dengan repositori proyek
• Akun Capgo dengan aplikasi yang sudah dikonfigurasi
• Node.js dan npm/yarn yang terkonfigurasi di proyek Anda

Mengatur GitLab CI/CD

Langkah 1: Konfigurasi Environment Variables

Pertama, atur variabel yang diperlukan di proyek GitLab Anda:

1. Buka proyek GitLab Anda
2. Buka Pengaturan → CI/CD → Variabel
3. Tambahkan variabel berikut:

Nama variabel	Nilai	Dilindungi	Disamarkan
CAPGO_TOKEN	Token Capgo API Anda	✅ Ya	✅ Ya

Tips

Dapatkan token Capgo API Anda dari console.capgo.app/apikeys. App ID Anda sudah dikonfigurasi di capacitor.config.ts file Anda.

Sederhana

Konfigurasi dasar untuk deploy ke production setiap kali push ke branch main:

# .gitlab-ci.yml - Simple Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  only:
    - main

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
    # For encrypted uploads, add: --key-data-v2 "$CAPGO_PRIVATE_KEY"
  dependencies:
    - build
  only:
    - main

Lanjutan

Deployment Feature Branch

Deploy feature branch ke test channel untuk review dan testing:

# Feature branch deployment
deploy_feature:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="feature-$(echo $CI_COMMIT_REF_NAME | sed 's/[^a-zA-Z0-9-]/-/g')"
    - npx @capgo/cli channel add $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - /^feature\/.*$/
  environment:
    name: feature/$CI_COMMIT_REF_NAME
    url: https://your-app.com/channels/$CHANNEL_NAME

Tips

Testing dengan Channels: Setelah deploy ke feature channel, Anda bisa menguji update di aplikasi Anda dengan mengonfigurasinya agar menggunakan channel tersebut. Pelajari lebih lanjut tentang konfigurasi channel di aplikasi Anda.

Menggunakan Enkripsi

Jika Anda menggunakan fitur enkripsi Capgo, Anda perlu menyimpan private key secara aman di lingkungan CI/CD Anda.

Setelah mengatur encryption keys secara lokal, tambahkan private key Anda ke variabel GitLab:

# Display your private key content (copy this output)
cat .capgo_key_v2

Tambahkan konten ini sebagai CAPGO_PRIVATE_KEY di variabel proyek GitLab Anda (tandai sebagai protected dan masked), lalu gunakan di pipeline:

# Deploy with encryption
deploy_production:
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --key-data-v2 "$CAPGO_PRIVATE_KEY" --channel production

Peringatan

Best Practices Keamanan:

• Jangan pernah commit .capgo_key_v2 file ke version control
• Simpan private key hanya di secret management CI/CD yang aman
• Gunakan key berbeda untuk tiap environment

Konfigurasi Multi-Channel

Untuk informasi lengkap mengenai setup dan pengelolaan banyak deployment channel, lihat dokumentasi Channels.

Konfigurasi lengkap dengan banyak environment dan deployment merge request:

# .gitlab-ci.yml - Advanced Multi-Channel Configuration
image: node:22

stages:
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"

# Build stage
build:
  stage: build
  script:
    - npm ci
    - npm run test
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 24 hours

# Deploy to development channel
deploy_development:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel development
  dependencies:
    - build
  only:
    - develop
  environment:
    name: development

# Deploy merge requests to test channels
deploy_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - CHANNEL_NAME="mr-$CI_MERGE_REQUEST_IID"
    - npx @capgo/cli channel add $CHANNEL_NAME --apikey $CAPGO_TOKEN || true
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL_NAME
  dependencies:
    - build
  only:
    - merge_requests
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    url: https://your-app.com/channels/mr-$CI_MERGE_REQUEST_IID
    on_stop: cleanup_mr

# Cleanup MR channels when MR is closed
cleanup_mr:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli channel delete mr-$CI_MERGE_REQUEST_IID --apikey $CAPGO_TOKEN || true
  when: manual
  environment:
    name: review/$CI_MERGE_REQUEST_IID
    action: stop
  only:
    - merge_requests

# Deploy to staging
deploy_staging:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel staging
  dependencies:
    - build
  only:
    - develop
  environment:
    name: staging

# Deploy to production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  environment:
    name: production

Multi-Environment dengan Approval Manual

Untuk deployment produksi yang butuh persetujuan manual:

deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  dependencies:
    - build
  only:
    - main
  when: manual
  environment:
    name: production

Strategi Deployment Berbasis Branch

Deploy berbagai branch ke channel yang sesuai secara otomatis:

# Dynamic channel deployment based on branch
deploy:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - |
      if [ "$CI_COMMIT_REF_NAME" = "main" ]; then
        CHANNEL="production"
      elif [ "$CI_COMMIT_REF_NAME" = "develop" ]; then
        CHANNEL="staging"
      else
        CHANNEL="development"
      fi
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel $CHANNEL
  dependencies:
    - build
  environment:
    name: $CHANNEL

Best Practice Keamanan

Variabel Terproteksi

1. Tandai Variabel Sensitif: Selalu tandai token API sebagai protected dan masked
2. Proteksi Branch: Gunakan variabel terproteksi untuk deployment produksi
3. Kontrol Akses: Batasi akses variabel hanya untuk maintainer
4. Rotasi Berkala: Rotasi token API secara berkala

Konfigurasi Pipeline Aman

# Use protected variables for production
deploy_production:
  stage: deploy
  script:
    - npm install -g @capgo/cli
    - npx @capgo/cli bundle upload --apikey $CAPGO_TOKEN --channel production
  only:
    refs:
      - main
    variables:
      - $CI_COMMIT_REF_PROTECTED == "true"

Monitoring dan Notifikasi

Integrasi Slack

Tambahkan notifikasi Slack ke pipeline Anda:

notify_success:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"✅ Capgo deployment successful for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_success

notify_failure:
  stage: .post
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
  script:
    - |
      curl -X POST -H 'Content-type: application/json' \
        --data '{"text":"❌ Capgo deployment failed for '"$CI_COMMIT_REF_NAME"'"}' \
        $SLACK_WEBHOOK_URL
  when: on_failure

Notifikasi Email

Konfigurasi notifikasi email di pengaturan proyek GitLab Anda atau gunakan API:

notify_email:
  stage: .post
  script:
    - |
      curl --request POST \
        --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
        --form "to=team@yourcompany.com" \
        --form "subject=Capgo Deployment Status" \
        --form "body=Deployment of $CI_COMMIT_REF_NAME completed with status: $CI_JOB_STATUS" \
        "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/emails"
  when: always

Pemecahan Masalah

Masalah Umum

Pipeline gagal dengan pesan “Capgo CLI not found”:

# Debug CLI installation
debug_cli:
  script:
    - npm install -g @capgo/cli
    - which capgo || echo "Capgo CLI not found"
    - npx @capgo/cli --version

Kesalahan autentikasi:

# Verify token configuration
debug_auth:
  script:
    - |
      if [ -z "$CAPGO_TOKEN" ]; then
        echo "CAPGO_TOKEN is not set"
        exit 1
      fi
      echo "Token length: ${#CAPGO_TOKEN}"

Artifact build tidak ditemukan:

# List build outputs
debug_build:
  script:
    - ls -la dist/
    - find dist/ -type f -name "*.js" -o -name "*.html"

Debug Pipeline

Tambahkan info debugging untuk troubleshooting masalah:

debug:
  stage: build
  script:
    - echo "Branch: $CI_COMMIT_REF_NAME"
    - echo "Commit: $CI_COMMIT_SHA"
    - echo "Build: $CI_PIPELINE_ID"
    - env | grep CI_ | sort
  only:
    - branches

Next Steps

• Pelajari tentang Channel untuk mengelola berbagai environment deployment
• Jelajahi Penyimpanan Kustom untuk skenario deployment tingkat lanjut
• Setup Enkripsi untuk deployment yang aman
• Konfigurasi Perilaku Update untuk kustomisasi cara update diterapkan

Dengan integrasi GitLab CI/CD, Anda dapat mengotomatiskan deployment Capgo dan memastikan update yang konsisten serta andal bagi pengguna aplikasi mobile Anda.

Lanjutkan dari Integrasi GitLab CI/CD

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