Pilih Otomatis Update Langsung atau Bangun Asli

Banyak rilis Capacitor adalah JavaScript-only dan harus dikirim sebagai update hidup. Beberapa perubahan menyentuh code native dan memerlukan biner baru dari Capgo Build. Panduan ini menunjukkan cara membuat GitHub Actions, GitLab CI, atau platform CI/CD lainnya memilih jalur yang tepat pada setiap push — tanpa manusia memutuskan.

Keputusan

Capgo sudah tahu mana jalur yang aman. Setelah build web Anda (dan sebelum Anda 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 channel. native berarti plugin, versi Capacitor, atau dependensi native lainnya berubah — paket udara secara daring tidak dapat memperbarui perangkat tersebut dengan aman.

releaseType menggabungkan metadata paket native (Capacitor/plugin Cordova dan versi). Hal itu tidak melihat setiap perubahan di ios/, android/, atau capacitor.config.*. Tutup jalur tersebut di git terlebih dahulu, kemudian gunakan releaseType untuk konsistensi dependensi — contoh di bawah ini melakukan kedua hal.

Lihat Kompatibilitas Asli aturan dan manual lengkapnya di bundle compatibility Tip

Jalankan setiap pipeline produksi pada

ini lebih murah daripada menebak, dan menghindari mengirimkan pembaruan hidup yang membuat perangkat yang masih menggunakan biner asli lebih tua mengalami crash. releaseTypePrasyarat

Bab berjudul “Prasyarat”

• Capgo Capgo API key di CI sebagai rahasia CAPGO_TOKEN
• Live Updates unggah bekerja (bundle upload) — lihat Integrasi CI/CD
• Capgo Kredensial Build di CI jika Anda mengharapkan pekerjaan native — lihat GitHub Aksi atau Kredensial
• Saluran yang sudah ada dan sesuai dengan produksi (contoh menggunakan production)
• Saluran pada metadata strategi sehingga setiap unggah dapat membawa --auto-min-update-version (satu kali):

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

Bagaimana Pipa Kerja 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. Pembangunan aset web seperti biasa.
2. Jika komit menyentuh ios/, android/, atau capacitor.config.*, paksa jalur native.
3. Jika tidak, tanyakan pada Capgo releaseType apakah komit aman untuk pembaruan OTA.
4. Jika OTAdan unggah dengan --fail-on-incompatible dan --auto-min-update-version.
5. Jika nativelakukan Capgo Build, kemudian unggah bundle yang sesuai dengan --auto-min-update-version sehingga metadata asli kanal maju. Lakukan tidak gunakan --fail-on-incompatible untuk unggah dasar itu — paket native baru seharusnya berbeda. Lihat Native + OTA Channel Workflow untuk FAQ kanal-level.

GitHub Aksi

Alur kerja yang mengatur jalur native, kemudian memisahkan pada releaseType:

github/alur-kerja/capgo-release.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 dalam GitHub Aksi untuk Capgo Bangun.

Perhatian

--fail-on-incompatible milik hanya pada pekerjaan OTA. Setelah Anda menambahkan saluran pada strategi, jangan metadata pada setiap unggahan (OTA dan native baseline). Setelah binary native berlayar, unggah paket yang sesuai dengan --auto-min-update-version dan tanpa --auto-min-update-version dan tanpa --fail-on-incompatible nanti kemudian releaseType periksa lihat paket native baru.

GitLab CI

GitLab mengevaluasi rules ketika pipeline dibuat, jadi cabang dengan shell if di dalam satu pekerjaan deploy (atau buatlah anak pipeline dinamis jika Anda membutuhkan pekerjaan matrix native terpisah): .gitlab-ci.yml

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

untuk branch dengan shell di dalam satu pekerjaan deploy (atau buatlah anak pipeline dinamis jika Anda membutuhkan pekerjaan matrix native terpisah): CAPGO_TOKEN dan Capgo Variabel tanda tangan Build sebagai variabel CI/CD tersembunyi.

Platform CI Lainnya

Langkah-langkah yang sama berlaku di mana saja:

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

Peta keluaran shell / stdout ke kondisional platform Anda (atau simpanlah satu pekerjaan dengan shell if, seperti GitLab di atas):

• Aliran Azure — atur variabel keluaran dari langkah skrip, kemudian gunakan condition: eq(variables['releaseType'], 'OTA')
• Aliran Pipelines Bitbucket — tulis RELEASE_TYPE=… ke $BITBUCKET_PIPELINES_VARIABLES_PATHcontext: Halaman/area: Halaman produk live update. Peran: Label UI singkat atau item navigasi. Kunci pesan `live_update_dynamic_label_to` (Label Live Update Dinamis To). output-variablesdan cabang langkah-langkah lain dengan condition: state: RELEASE_TYPE == "OTA" (artefak file sendiri tidak dapat mengemudikan condition)
• Aliran CI Circle — when dievaluasi pada waktu kompilasi konfigurasi, sehingga cabang dengan shell waktu eksekusi if (atau konfigurasi dinamis / lanjutan), bukan nilai workspace di when
• Jenkins --- tangkap stdout ke variabel lingkungan dan gunakan when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Pemfilter Jalur (Optimalisasi Kecepatan Opsional)

Pemfilter jalur adalah optimasi biaya, bukan pengganti untuk pengecekan Capgo. Lebih baik menghilangkan jalur dokumen saja daripada memelihara daftar yang rapuh — pembangunan web sering juga bergantung pada vite.config.*, tsconfig*.json, dan file konfigurasi framework:

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

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

Setelah Putusan Asli

Ketika CI memilih asli:

1. Capgo Pembangunan menghasilkan file biner yang ditandatangani dan dapat mengirimkan ke TestFlight / Play (lihat Konfigurasi).
2. Upload bundle JS yang sesuai dengan --auto-min-update-version (strategi metadata) sehingga channel mencatat paket native baru — jika tidak, komit JavaScript saja akan kembali native.
3. Setelah pengguna menginstal biner baru, komit JavaScript saja akan kembali ke OTA Kembali lagi.

Referensi Lainnya

Kompatibilitas Native Mengapa Capgo mengembalikan OTA vs native dan bagaimana menghentikan unggahan yang salah.

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

GitHub Aksi (Capgo Build) Signing rahasia dan alur pembangunan native penuh.

Mulai Bangun dari UI CI Jalankan pembangunan native secara on demand dari GitHub, GitLab, atau Bitbucket.

Mulai Bangun melalui Webhook Mulai Bangun Capgo dari dashboard admin atau klien HTTP mana saja.