Pilih Otomatis Live Update atau Bangun Natively

Sebagian besar rilis Capacitor adalah JavaScript-only dan harus dikirim sebagai live update. Beberapa perubahan menyentuh native code dan memerlukan biner baru dari Capgo Pembangunan. This guide shows how to make GitHub Actions, GitLab CI, or any other CI/CD platform pick the correct path on every push — without a human deciding.

Keputusan

Capgo sudah tahu jalur yang aman. Setelah Anda melakukan build web (dan sebelum mengunggah atau meminta build native), jalankan:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      ship with bundle upload
# → native   ship with Capgo Build

OTA berarti paket native sesuai dengan yang sudah hidup di saluran. native berarti plugin, versi Capacitor, atau dependensi native lainnya berubah — paket udara melalui udara tidak dapat memperbarui perangkat tersebut dengan aman.

releaseType mengumpulkan metadata paket native (Capacitor/plugin Cordova dan versi). Ini tidak not Lihat setiap perubahan di bawah ios/, android/, or capacitor.config.*. Gate those paths in git first, then use releaseType untuk konsistensi dependensi — contoh di bawah ini melakukan kedua hal.

See Kompatibilitas Asli untuk aturan-aturan penuh dan manual bundle compatibility meja.

Tip

Jalankan setiap pipa produksi pada releaseTypeLebih murah daripada menebak, dan menghindari mengirimkan aplikasi live update yang mengakibatkan perangkat masih menggunakan binary asli asli mengalami kacau.

Prerequisites

• Aplikasi Capgo terdaftar dan sebuah Capgo API kunci dalam rahasia CI sebagai CAPGO_TOKEN
• Update Hidup secara Langsung unggah bekerja (bundle upload) — lihat Integrasi CI/CD
• Capgo Build credentials in CI if you expect native jobs — see GitHub Actions or Credentials
• Salah satu saluran yang sudah ada dan sesuai dengan produksi (contoh-contoh menggunakan) production)
• Saluran di metadata Jika Anda mengharapkan pekerjaan asli — lihat --auto-min-update-version (one-time):

npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

Bagaimana Pipa Harus Berjalan

flowchart TD
  A[Push / merge] --> B[Install + web build]
  B --> C["bundle releaseType"]
  C -->|OTA| D["bundle upload"]
  C -->|native| E["build request iOS + Android"]
  E --> F[Store / TestFlight / Play]

1. Bangun aset web seperti biasa.
2. Jika komit menyentuh ios/, android/, atau capacitor.config.*, paksa jalur native.
3. Jika tidak, tanyakan kepada Capgo releaseType apakah komit aman untuk OTA.
4. Jika OTA, unggah dengan --fail-on-incompatible dan --auto-min-update-version.
5. Jika native, jalankan Capgo Build, kemudian unggah bundle yang sesuai dengan --auto-min-update-version sehingga metadata native kanal maju. Tidak gunakan use --fail-on-incompatible untuk dasar upload tersebut — paket native baru seharusnya berbeda. Lihat untuk FAQ kanal-level. __CAPGO_KEEP_0__ Actions

Bab yang berjudul “GitHub Actions”

Satu alur kerja yang mengatur jalur asli, kemudian memisahkan ke dalam releaseType:

/github/aliran kerja/capgo-rilis.yml

name: Capgo Release

on:
  push:
    branches: [main]

jobs:
  decide:
    runs-on: ubuntu-latest
    outputs:
      release_type: ${{ steps.verdict.outputs.type }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Decide OTA vs native
        id: verdict
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          BEFORE="${{ github.event.before }}"
          if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
            BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')"
          fi
          if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "${{ github.sha }}" \
            | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
            TYPE=native
            echo "Native path/config changed (or no prior commit) — forcing native"
          else
            TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]')
          fi
          echo "type=$TYPE" >> "$GITHUB_OUTPUT"
          echo "Capgo release type: $TYPE"

  live_update:
    needs: decide
    if: needs.decide.outputs.release_type == 'OTA'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Upload live update
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          npx @capgo/cli@latest bundle upload com.example.app \
            --channel production \
            --fail-on-incompatible \
            --auto-min-update-version

  native_build:
    needs: decide
    if: needs.decide.outputs.release_type == 'native'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - run: npx cap sync ${{ matrix.platform }}
      - name: Capgo Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          npx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

  native_bundle:
    needs: [decide, native_build]
    if: needs.decide.outputs.release_type == 'native'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Upload bundle for new native baseline
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          # Channel must already be on metadata (see Prerequisites above)
          npx @capgo/cli@latest bundle upload com.example.app \
            --channel production \
            --auto-min-update-version

Ganti com.example.app dan hubungkan rahasia tanda tangan seperti yang dijelaskan di GitHub Aksi untuk Capgo Bangun.

Catatan

--fail-on-incompatible harus ada di pekerjaan OTA saja. Setelah Anda menempatkan saluran di strategi, jaga metadata pengaturan, tetapkan --auto-min-update-version setiap unggahan (OTA dan native baseline). Setelah binary native dikirim, unggah bundle yang sesuai dengan. --auto-min-update-version sehingga kemudian --fail-on-incompatible Nanti releaseType periksa paket native baru.

GitLab CI

GitLab mengevaluasi rules ketika pipeline dibuat, sehingga cabang dengan shell if dalam satu pekerjaan deploy (atau buatlah) pipa anak dinamis Jika Anda memerlukan pekerjaan matrix native terpisah):

Salin ke clipboard

image: node:24

stages:
  - build
  - deploy

variables:
  APP_ID: com.example.app
  CHANNEL: production

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

deploy:
  stage: deploy
  needs: [build_web]
  script:
    - |
      BEFORE="${CI_COMMIT_BEFORE_SHA:-}"
      if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
        BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')"
      fi
      if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "$CI_COMMIT_SHA" \
        | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
        TYPE=native
      else
        TYPE=$(npx @capgo/cli@latest bundle releaseType "$APP_ID" --channel "$CHANNEL" | tr -d '[:space:]')
      fi
      echo "Capgo release type: $TYPE"
      if [ "$TYPE" = "OTA" ]; then
        npx @capgo/cli@latest bundle upload "$APP_ID" \
          --channel "$CHANNEL" \
          --fail-on-incompatible \
          --auto-min-update-version
      elif [ "$TYPE" = "native" ]; then
        npx cap sync
        npx @capgo/cli@latest build request "$APP_ID" --platform ios --build-mode release
        npx @capgo/cli@latest build request "$APP_ID" --platform android --build-mode release
        npx @capgo/cli@latest bundle upload "$APP_ID" \
          --channel "$CHANNEL" \
          --auto-min-update-version
      else
        echo "Unexpected release type: $TYPE" >&2
        exit 1
      fi
  only:
    - main

Store CAPGO_TOKEN dan Capgo Variabel signing build sebagai variabel CI/CD tersembunyi.

Lainnya Platform CI

Langkah-langkah yang sama tiga bekerja di mana saja:

Langkah	Perintah
Hasil	npx @capgo/cli@latest bundle releaseType APP_ID --channel production
Jalan Update OTA	npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Jalan OTA	npx @capgo/cli@latest build request APP_ID --platform ios (or android) --build-mode release

Mapkan keluaran shell / stdout ke kondisional platform Anda (atau simpanlah satu pekerjaan dengan shell) ifseperti di GitLab di atas):

• Azure Pipelines — atur variabel keluaran dari langkah skrip, kemudian gunakan condition: eq(variables['releaseType'], 'OTA')
• Pipelines Bitbucket — tulis RELEASE_TYPE=… ke $BITBUCKET_PIPELINES_VARIABLES_PATHdeklarasikan di bawah output-variables, deklarasikan di bawah condition: state: RELEASE_TYPE == "OTA" , dan cabang langkah-langkah berikutnya dengan condition)
• CircleCI — when di evaluasi pada waktu kompilasi konfigurasi, jadi cabang dengan shell waktu eksekusi if dievaluasi pada waktu kompilasi konfigurasi, sehingga cabang dengan shell waktu eksekusi when
• Jenkins — tangkap stdout ke dalam variabel lingkungan dan gunakan when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Jalur Filter (Pengurangan Kecepatan Opsional)

Path filters are a cost optimization, not a substitute for the Capgo check. Prefer excluding docs-only paths rather than maintaining a fragile allowlist — web builds often also depend on vite.config.*, tsconfig*.jsondan konfigurasi file framework:

on:
  push:
    branches: [main]
    paths-ignore:
      - '**.md'
      - 'docs/**'
      - '.github/**'

Jika Anda menggunakan daftar yang diizinkan, masukkan setiap input yang dibaca oleh pembangunan web dan native, bukan hanya src/ dan package.json.

Setelah Putusan Native

Ketika CI memilih native:

1. Capgo Membangun produksi file biner yang ditandatangani dan dapat mengirimkan ke TestFlight / Play (lihat Konfigurasi).
2. Unggah bundle JS yang sesuai dengan --auto-min-update-version Strategi metadata — sehingga saluran merekam paket native baru — jika tidak, komit JS-only berikutnya masih mengembalikan native.
3. Setelah pengguna menginstal biner baru, komit JavaScript-only kemudian mengembalikan OTA lagi.

Tautan Panduan Terkait

Kompatibilitas Native Mengapa Capgo mengembalikan OTA vs native dan bagaimana menghalangi unggahan buruk.

Alur Kerja Saluran Native + OTA Saluran dev/prod dan kapan menggugurkan --fail-on-incompatible untuk dasar native sengaja.

Aksi GitHub (Capgo Build) Rahasia tanda tangan dan alur kerja penuh native.

Trigger Build dari UI CI Jalankan pembangunan native secara on demand dari GitHub, GitLab, atau Bitbucket.

Trigger Pembangunan melalui Webhook Jalankan Pembangunan Capgo dari dashboard admin atau klien HTTP mana saja.