Pilih Otomatis Update Langsung atau Bangun Asli

Salin prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

Sebagian besar 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 yang 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 channel. native berarti plugin, versi Capacitor, atau dependensi native lainnya berubah — paket udara tunggal tidak dapat memperbarui perangkat tersebut dengan aman.

releaseType menggambarkan 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 untuk aturan-aturan penuh dan manual bundle compatibility tabel.

Prasyarat

Capgo aplikasi terdaftar dan sebuah Capgo API kunci dalam rahasia CI sebagai CAPGO_TOKEN
Perbaruan Hidup unggah bekerja (bundle upload— lihat Integrasi CI/CD
Capgo Kredensial Bangun jika Anda mengharapkan pekerjaan asli — lihat GitHub Aksi atau Kredensial
Nama saluran yang sesuai dengan produksi (contoh menggunakan production)

Bagaimana Pipa Harus Berfungsi

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]

Bangun aset web seperti biasa.
Jika komit menyentuh ios/, android/, atau capacitor.config.*, paksa jalur native.
Jika tidak, tanyakan kepada Capgo releaseType apakah komit aman untuk OTA.
Jika OTA, unggah bundle (dengan --fail-on-incompatible sebagai pengamanan).
Jika native, jalankan Capgo Build, kemudian unggah bundle yang sesuai dengan --auto-min-update-version agar metadata native channel maju (gunakan strategi metadata __CAPGO_KEEP_0__. Do tidak gunakan --fail-on-incompatible untuk upload dasar — paket native baru diharapkan berbeda.

GitHub Aksi

Satu alur kerja yang mengatur jalur native, kemudian memisahkan pada releaseType:

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

  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: |
          # One-time: channel set production --disable-auto-update metadata
          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 Build.

GitLab CI

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

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
      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

Simpan CAPGO_TOKEN dan Capgo Variabel tanda tangan Build disembunyikan sebagai variabel CI/CD yang dilindungi.

Lainnya Platform CI

Tiga langkah yang sama berlaku di mana saja:

Langkah	Perintah
Hasil	`npx @capgo/cli@latest bundle releaseType APP_ID --channel production`
Rute OTA	`npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible`
Rute 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 pekerjaan tunggal dengan shell) if:)

Azure Pipelines — atur variabel output dari langkah skrip, kemudian gunakan condition: eq(variables['releaseType'], 'OTA')
Bitbucket Pipelines — tulis RELEASE_TYPE=… ke $BITBUCKET_PIPELINES_VARIABLES_PATHdeclare di bawah output-variablesdan cabang langkah-langkah kemudian dengan condition: state: RELEASE_TYPE == "OTA" (artefak file sendiri tidak dapat mengemudikan condition)
CircleCI — 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' }

Filter Jalur (Optimasi Biaya Opsional)

Filter jalur adalah optimasi biaya, bukan pengganti untuk pengecekan Capgo. vite.config.*, tsconfig*.jsonLebih baik menghilangkan jalur dokumen saja daripada memelihara daftar yang rapuh — bangun web sering juga bergantung pada

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

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

dan (Anda juga dapat menggunakan kata ini untuk menyambungkan dua kalimat atau ide yang berbeda, seperti di halaman ini). Context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).

Ketika CI memilih asli:

Capgo Pembangunan menghasilkan file biner yang ditandatangani dan dapat mengirimkan ke TestFlight / Play (lihat konfigurasi).
Unggah bundle JS yang sesuai dengan --auto-min-update-version (strategi metadata) sehingga saluran mencatat paket asli baru — jika tidak, komit JavaScript saja berikutnya masih akan kembali native.
Setelah pengguna menginstal biner baru, komit JavaScript saja kemudian kembali ke OTA lagi.

Kompatibilitas Asli Mengapa Capgo mengembalikan OTA vs asli dan bagaimana menghalangi unggahan yang salah.

GitHub Aksi (Capgo Bangun) Tanda tangan rahasia dan alur kerja bangun native penuh.

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

Mulai Bangun melalui Webhook Jalankan Capgo Bangun dari dashboard admin atau klien HTTP apa pun.