본문 바로가기
Capgo - Capacitor 앱 빌드, 배포 및 업데이트 Capgo

CI UI에서 Native Build 트리거하기

PR을 머지하거나 릴리스 태그를 생성하지 않고도 QA 빌드, 스토어 재제출, 또는 일회성 TestFlight용 iOS/Android 서명된 바이너리가 필요할 때가 있습니다. 대부분의 주요 code 호스트는 웹 UI에서 직접 파이프라인을 시작할 수 있습니다. 이 가이드에서는 해당 UI를 Capgo Build에 연결하는 방법을 설명합니다.

제공되는 항목

“주요 기능” 섹션

번거로운 Git 작업 불필요

Run workflow 또는 Run pipeline을 클릭하세요. Capgo Build는 선택한 브랜치에서 바로 컴파일을 시작합니다.

안전한 입력값

호스트가 지원하는 경우(GitHub / Bitbucket / Azure), 플랫폼 및 빌드 모드는 제한된 선택지를 사용합니다. GitLab 변수는 별도로 정의하지 않는 한 실행 시마다 수정할 수 있습니다. pipeline 입력값 포함 options.

CI와 동일한 Secret 사용

리포지토리에 이미 있는 Capgo Build 인증 정보를 재사용하세요. 로컬 환경에 새로 설정할 필요가 없습니다.

사전 요구사항

“사전 준비 사항” 섹션

GitHub 작업

“GitHub Actions” 섹션

GitHub의 액션 탭에서 선언하는 모든 워크플로를 시작할 수 있습니다. workflow_dispatch.

1. 워크플로우 추가

“1. 워크플로 추가” 섹션
.github/workflows/capgo-build-manual.yml
name: Capgo Build (Manual)


on:
  workflow_dispatch:
    inputs:
      platform:
        description: Platform to build
        required: true
        default: both
        type: choice
        options: [ios, android, both]
      mode:
        description: Build mode
        required: true
        default: debug
        type: choice
        options: [debug, release]
      ref_note:
        description: Optional note for the run summary
        required: false
        type: string


jobs:
  build:
    runs-on: ubuntu-latest
    environment: ${{ inputs.mode == 'release' && 'production' || 'build-debug' }}
    strategy:
      fail-fast: false
      matrix:
        platform: ${{ fromJSON(inputs.platform == 'both' && '["ios","android"]' || format('["{0}"]', inputs.platform)) }}
    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
        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: |
          EXTRA=""
          if [ "${{ inputs.mode }}" = "debug" ] && [ "${{ matrix.platform }}" = "android" ]; then
            EXTRA="--no-playstore-upload --output-upload"
          fi
          npx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode ${{ inputs.mode }} \
            $EXTRA

2. UI에서 실행

“2. UI에서 실행” 섹션
  1. 브라우저에서 GitHub 리포지토리를 엽니다
  2. 다음으로 이동: 액션
  3. 선택 Capgo Build (수동)
  4. 클릭 워크플로 실행을
  5. 브랜치, 플랫폼, 모드를 선택하세요
  6. 확인 워크플로 실행을

다음 권한이 있는 사용자는 쓰기 액세스 권한으로 빌드를 시작할 수 있습니다. 샘플은 release GitHub 환경인 다음 이름의 환경으로 실행됩니다: production — 해당 환경을 생성하고 필수 검토자를 추가하여 빌드 승인을 대기하도록 설정하세요. 설정하지 않으면 environment: 작업에서 환경 보호 규칙이 적용되지 않습니다.

GitLab CI

“GitLab CI”라는 제목의 섹션

GitLab에서 다음 경로로 작업을 실행할 수 있습니다: Build → Pipelines → pipeline 실행 해당 브랜치에서 작업이 가능한 경우.

# Job fragment for .gitlab-ci.yml
stages:
  - build


variables:
  APP_ID: com.example.app
  PLATFORM: android   # override from Run pipeline UI
  BUILD_MODE: debug


capgo_native_manual:
  stage: build
  when: manual
  script:
    - npm ci
    - npm run build
    - npx cap sync "$PLATFORM"
    - |
      npx @capgo/cli@latest build request "$APP_ID" \
        --platform "$PLATFORM" \
        --build-mode "$BUILD_MODE"
  rules:
    # Actions / Pipelines UI → manual play button
    - if: '$CI_PIPELINE_SOURCE == "web"'
      when: manual
    # Pipeline trigger token / webhook → run automatically
    - if: '$CI_PIPELINE_SOURCE == "trigger"'
      when: on_success
    - when: never
  1. GitLab 프로젝트 열기
  2. 다음으로 이동: Build → Pipelines → pipeline 실행
  3. 브랜치 선택
  4. 선택 사항: PLATFORM / BUILD_MODE 이번 실행을 위한 변수 설정
  5. 파이프라인을 시작한 후, 다음의 재생 버튼을 클릭하세요: capgo_native_manual

when: manual 푸시할 때마다 작업이 실행되는 것을 방지하며, 웹 UI(또는 파이프라인 트리거 토큰)를 통해 필요할 때마다 실행할 수 있습니다.

Bitbucket Pipelines

“Bitbucket Pipelines” 섹션

Bitbucket UI에서 변수를 전달할 수 있도록 커스텀 파이프라인을 사용하세요:

bitbucket-pipelines.yml
pipelines:
  custom:
    capgo-native-build:
      - variables:
          - name: PLATFORM
            default: android
            allowed-values:
              - ios
              - android
          - name: BUILD_MODE
            default: debug
            allowed-values:
              - debug
              - release
      - step:
          name: Capgo Build
          image: node:24
          script:
            - npm ci
            - npm run build
            - npx cap sync "$PLATFORM"
            - npx @capgo/cli@latest build request com.example.app --platform "$PLATFORM" --build-mode "$BUILD_MODE"

다음에서 실행하세요: Pipelines → Run pipeline → Custom: capgo-native-build. 저장: CAPGO_TOKEN 및 서명 자료는 다음 위치에: 저장소 설정 → Pipelines → Repository variables.

Azure DevOps

“Azure DevOps” 섹션
azure-pipelines-capgo-manual.yml
trigger: none   # disable CI push triggers
pr: none        # also disable PR triggers (GitHub/Bitbucket-backed projects)


parameters:
  - name: platform
    displayName: Platform
    type: string
    default: android
    values:
      - ios
      - android
  - name: buildMode
    displayName: Build mode
    type: string
    default: debug
    values:
      - debug
      - release


pool:
  vmImage: ubuntu-latest


steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '24.x'
  - script: |
      npm ci
      npm run build
      npx cap sync ${{ parameters.platform }}
      npx @capgo/cli@latest build request com.example.app \
        --platform ${{ parameters.platform }} \
        --build-mode ${{ parameters.buildMode }}
    env:
      CAPGO_TOKEN: $(CAPGO_TOKEN)
      # map other signing secrets from Library → Variable groups

trigger: none 및 pr: none CI/PR 자동 실행 시 파이프라인이 돌아가지 않도록 설정하여, Pipelines → 파이프라인 실행 (또는 webhook으로) 직접 시작할 수 있게 하세요. 만약 Azure Repos의 브랜치 정책으로 인해 파이프라인이 대기열에 추가된다면, 해당 정책을 별도로 비활성화해야 합니다. 그 다음, CAPGO_TOKEN signing 값을 secret으로 설정된 variable group에 추가하세요.

“Recommended Inputs” 섹션
입력권장 값참고 사항
플랫폼ios, android, bothMatrix 사용 시점 both
모드debug, release디버그 + --output-upload QA 링크용
iOS 배포app_store, ad_hocAd-hoc은 App Store에 제출되지 않습니다

다운로드 가능한 QA 아티팩트를 만들려면 debug Android를 다음 항목과 조합하세요 --no-playstore-upload --output-upload 그리고 URL은 다음으로 읽으세요 build last-output.

보안 참고 사항

“보안 참고 사항” 섹션
  • 다음 대상에는 환경 보호 규칙(GitHub) 또는 보호된 변수(GitLab) 사용을 권장합니다: release 스토어에 제출하는 빌드.
  • 워크플로에 서명 비밀번호를 직접 입력하지 마세요. inputs — secrets/variables에만 보관하세요.
  • 레포지토리 역할과 팀 권한으로 워크플로 실행 권한을 제한하세요 (GitHub에 대한 write access 필요). 브랜치 보호만으로는 워크플로 실행을제어할 수 없으므로, 더 좁은 그룹만 빌드를 시작해야 한다면 워크플로 내 권한 확인 단계를 추가하세요.
“관련 가이드” 섹션
GitHub Actions (전체 설정) 자격 증명을 내보내고 워크플로를 push/tag 하세요.
자동 OTA 또는 Native 매 push마다 CI가 live update 또는 Capgo Build를 선택하도록 하세요.
Webhook으로 트리거하기 관리자 대시보드에서 HTTP를 통해 동일한 파이프라인을 호출하세요.