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 benar pada setiap push — tanpa manusia memutuskan.

Keputusan

Capgo sudah tahu mana jalur yang aman. Setelah pembangunan web Anda (dan sebelum Anda mengunggah atau meminta pembangunan 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 melihat setiap edit di , atau ios/, android/. Tutup jalur itu di git terlebih dahulu, kemudian gunakan capacitor.config.*untuk konsistensi dependensi — contoh di bawah ini melakukan kedua hal. releaseType mengumpulkan

Lihat Kompatibilitas Asli aturan dan manual lengkap bundle compatibility daftar tabel.

Trik

Jalankan setiap pipeline produksi pada releaseTypeLebih murah daripada menebak, dan menghindari mengirimkan pembaruan hidup yang membuat perangkat masih menggunakan binary asli yang lebih tua.

Prasyarat

• Aplikasi Capgo terdaftar dan memiliki kunci __CAPGO_KEEP_1__ Capgo Capgo API key di CI rahasia sebagai 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 penggunaan production)
• Saluran pada metadata strategi sehingga setiap unggahan 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 native kanal maju. Lakukan tidak gunakan --fail-on-incompatible untuk upload dasar itu — paket native baru diharapkan berbeda. Lihat Native + OTA Channel Workflow untuk FAQ kanal-level.

GitHub Aksi

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

.github/alur/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.

Catatan

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

GitLab CI

GitLab mengevaluasi rules ketika pipeline dibuat, jadi cabang dengan shell if dalam satu pekerjaan deploy (atau buatlah anak pipeline dinamis jika Anda memerlukan 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 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 simpan satu pekerjaan dengan shell if, seperti GitLab di atas):

• Azure Pipelines — set an output variable dari langkah script, kemudian gunakan condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — tuliskan RELEASE_TYPE=… ke $BITBUCKET_PIPELINES_VARIABLES_PATHdeclare di bawah output-variablesdan cabang langkah-langkah lain dengan condition: state: RELEASE_TYPE == "OTA" file artifact sendiri tidak dapat mengendalikan condition)
• CircleCI — when diamati pada waktu konfigurasi-kompilasi, sehingga cabang dengan shell waktu eksekusi if atau konfigurasi dinamis / lanjutan, bukan nilai workspace di when
• Jenkins --- tangkap stdout ke dalam variabel lingkungan dan gunakan when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Pengaturan Jalur (Optimasi Kecepatan Opsional)

Pengaturan jalur adalah optimasi biaya, bukan pengganti untuk pengecekan Capgo. Lebih baik menghilangkan jalur dokumen saja daripada memelihara daftar yang rapuh — pembangunan web seringkali 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 binary baru, komit JavaScript saja akan kembali ke OTA Kembali lagi.

Petunjuk Terkait

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

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

GitHub Aksi (Capgo Build) Proses tanda tangan rahasia dan alur pembangunan native penuh.

Mulai Proses Pembangunan dari Antarmuka CI Jalankan pembangunan native secara on demand dari GitHub, GitLab, atau Bitbucket.

Mulai Proses Pembangunan melalui Webhook Mulai Proses Pembangunan Capgo dari dashboard admin atau klien HTTP apa pun.