Live Update 또는 Native Build 자동 선택

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

대부분의 Capacitor 릴리스는 JavaScript만 포함하므로 다음과 같이 배포해야 합니다 live update를. 일부 변경 사항은 네이티브 code에 영향을 주므로 다음을 통해 새로운 바이너리를 생성해야 합니다: Capgo 빌드. 이 가이드는 사람이 직접 결정할 필요 없이, GitHub Actions, GitLab CI 또는 기타 CI/CD 플랫폼이 푸시할 때마다 올바른 경로를 선택하도록 설정하는 방법을 설명합니다.

결정

Capgo는 어떤 경로가 안전한지 이미 알고 있습니다. 웹 빌드 완료 후(업로드 또는 Native Build 요청 전) 다음 명령어를 실행하세요:

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

OTA 는 네이티브 패키지가 현재 채널에 배포된 상태와 일치함을 의미합니다. native 는 플러그인, Capacitor 버전 또는 기타 네이티브 의존성이 변경되었음을 의미합니다. 이 경우 OTA 번들만으로는 기기를 안전하게 업데이트할 수 없습니다.

releaseType 비교 네이티브 패키지 메타데이터 (Capacitor/Cordova 플러그인과 버전). 이는 하지 마세요 아래의 모든 변경 사항 보기 ios/, android/, 또는 capacitor.config.*. git에서 해당 경로를 먼저 제한한 다음 사용하세요 releaseType 의존성 호환성을 위해 — 아래 예시는 두 가지 모두를 수행합니다.

자세한 내용은 Native 호환성 전체 규칙과 매뉴얼 bundle compatibility 표.

사전 요구사항

Capgo 앱이 등록되어 있고 Capgo API 키 를 CI secrets에 다음으로 설정하여 CAPGO_TOKEN
Live Updates 업로드 작동 확인 (bundle upload) — CI/CD 통합
네이티브 작업이 예상되는 경우 CI에 Capgo Build 자격 증명을 설정하세요 — GitHub 작업 또는 인증 정보
이미 존재하며 프로덕션 환경과 일치하는 채널(예시에서는 production)
채널을 metadata 전략을 사용하여 모든 upload가 --auto-min-update-version (1회성):

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

파이프라인 동작 방식

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]

평소와 같이 웹 에셋을 build합니다.
커밋이 다음을 건드리면 ios/, android/, 또는 capacitor.config.*, Native Build 경로를 강제하세요.
그렇지 않으면 Capgo에게 releaseType 커밋이 OTA에 안전한지 물어보세요.
만약 OTA, ...로 upload하세요 --fail-on-incompatible 및 --auto-min-update-version.
만약 native, Capgo Build를 실행한 뒤, 일치하는 번들을 ...로 upload하여 --auto-min-update-version 채널의 native metadata가 업데이트되도록 하세요. 하지 마세요 사용하세요 --fail-on-incompatible 해당 베이스라인 업로드용입니다. 새 네이티브 패키지는 서로 달라야 합니다. 자세한 내용은 Native + OTA 채널 워크플로우 채널 레벨 FAQ를 참조하세요.

GitHub 작업

네이티브 경로를 게이트한 다음, 조건에 따라 분기하는 하나의 워크플로우입니다. 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 \
            --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

교체 com.example.app 그리고 다음 문서에 설명된 대로 서명 시크릿을 연결하세요. Capgo Build용 GitHub Actions.

GitLab CI

GitLab은 rules pipeline이 생성될 때 평가하므로, shell이 포함된 브랜치는 if 하나의 deploy job 안에서(또는 동적 child pipeline을 생성, 별도의 native matrix job이 필요하면):

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

스토어 CAPGO_TOKEN 및 Capgo Build 서명 변수를 masked/protected CI/CD 변수로 설정하세요.

기타 CI 플랫폼

동일한 세 단계가 어디서나 적용됩니다:

단계	명령어
결론	`npx @capgo/cli@latest bundle releaseType APP_ID --channel production`
OTA 경로	`npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version`
네이티브 경로	`npx @capgo/cli@latest build request APP_ID --platform ios` (또는 `android`) `--build-mode release`

셸의 exit 코드나 stdout을 플랫폼 조건문으로 매핑하세요 (또는 위 GitLab 예시처럼 단일 job을 유지할 수도 있습니다): if, 위 GitLab 예시와 같이):

Azure Pipelines — 스크립트 단계에서 출력 변수를 설정한 후 사용하세요 condition: eq(variables['releaseType'], 'OTA')
Bitbucket Pipelines — 작성하고 RELEASE_TYPE=… 대상 $BITBUCKET_PIPELINES_VARIABLES_PATH, 아래에 선언하세요 output-variables, 그리고 이후 브랜치 단계를 condition: state: RELEASE_TYPE == "OTA" (파일 아티팩트만으로는 condition)
CircleCI — when 는 config-compile 시점에 평가되므로, 런타임 셸을 사용하여 브랜치 분기를 처리해야 합니다 if (또는 동적 설정/continuation), workspace 값이 아닌 when
Jenkins를 — stdout을 환경 변수에 캡처하여 사용하세요 when { environment name: 'RELEASE_TYPE', value: 'OTA' }

경로 필터 (선택적 속도 향상)

Path filter는 비용 최적화 도구이며 Capgo 체크를 대체하는 것이 아닙니다. 취약한 allowlist를 유지하기보다는 docs 전용 경로를 제외하는 방식을 권장합니다. 웹 빌드는 종종 다음 항목에도 의존합니다: vite.config.*, tsconfig*.json, 그리고 프레임워크 설정 파일:

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

대신 allowlist를 사용한다면, 다음뿐 아니라 웹 및 native build가 읽는 모든 입력을 포함하세요. src/ 및 package.json.

Native Verdict 이후

CI가 native를 선택한 경우:

Capgo Build는 서명된 바이너리를 생성하고 TestFlight / Play에 제출할 수 있습니다(참고 설정).
일치하는 JS bundle을 다음으로 upload하세요 --auto-min-update-version (metadata strategy)를 사용해 채널이 새 native 패키지를 기록하도록 합니다. 그렇지 않으면 다음 JS-only commit에서도 여전히 native.
사용자가 새 바이너리를 설치하면, 이후 JavaScript-only commit은 다시 OTA 다시.

Native 호환성 Capgo가 native 대신 OTA를 반환하는 이유와 잘못된 upload를 차단하는 방법.

Native + OTA 채널 워크플로우 Dev/production 채널, 그리고 의도적인 native baseline을 위해 --fail-on-incompatible을 제거해야 하는 시점.

GitHub 액션 (Capgo Build) Signing secrets 및 전체 native build 워크플로우.

CI UI에서 Build 트리거하기 GitHub, GitLab 또는 Bitbucket에서 원할 때 native build 실행하기.

Webhook으로 Build 트리거하기 관리자 대시보드나 HTTP 클라이언트에서 Capgo Build 실행하기.