내용으로 건너뛰기
Capgo - Capacitor을 빌드, 배포 및 업데이트 하세요 Capgo

웹 훅을 통해 네이티브 빌드를 트리거하세요

Capgo 일반적으로 laptop 또는 CI 작업에서 빌드를 시작합니다. CMS, 내부 포털 또는 관리자 대시보드에서 배포하는 팀은 단일 관리자 대시보드, CMS, 또는 내부 포털에서 배포하는 팀은 단일 HTTP 웹 훅: 사용자의 UI에서 버튼을 클릭하고, 서명된 네이티브 빌드가 시작됩니다. 이 안내서에서는 표준 패턴을 보여줍니다 — 사용자의 code 호스트에 대한 얇은 인증된 HTTP 호출, 이 호스트는 사용자가 이미 사용하는 Capgo 빌드 워크플로를 실행합니다.

구조

구조

당신은 필요하지 않습니다 Capgo를 공개하는 "빌드 웹 훅"을 노출할 필요가 없습니다. CI가 이미 서명 비밀을 가지고 있습니다. 웹 훅의 일은 CI 작업을 안전하게 시작하는 것입니다.

필요 조건

필요 조건
  • Capgo 빌드 워크플로우가 CI UI에서 이미 작동하고 있거나 푸시 ( CI UI __CAPGO_KEEP_0__ 토큰, GitLab 트리거 토큰, 또는 동등한 권한이 있는 경우GitHub 액션)
  • GitHub
  • __CAPGO_KEEP_0__

Option A — GitHub repository_dispatch (추천)

Option A — GitHub repository_dispatch (추천)

GitHub는 인증된 API 호출을 받고 GitHub가 웹후크를 듣는 워크플로우를 시작합니다. repository_dispatch. 어떤 대시보드라도 POST JSON은 그것을 발동시킬 수 있습니다.

1. 웹후크를 듣는 워크플로우

Section titled “1. 웹후크를 듣는 워크플로우”

웹후크의 내용을 검증합니다. 웹후크를 받기 전에 체크아웃하고 비밀번호를 포함하는 단계를 실행하기 전에. accepted values를 job outputs / env vars를 통해 전달하고 interpolate하지 마십시오. client_payload 직접 웹후크의 내용에 넣지 마십시오. run: 스크립트 (스크립트 주입 지침).

github/워크플로우/capgo-빌드-웹훅.yml
name: Capgo Build (Webhook)


on:
  repository_dispatch:
    types: [capgo-native-build]


jobs:
  validate:
    runs-on: ubuntu-latest
    outputs:
      platform: ${{ steps.check.outputs.platform }}
      mode: ${{ steps.check.outputs.mode }}
      ref: ${{ steps.check.outputs.ref }}
      platforms_json: ${{ steps.check.outputs.platforms_json }}
    steps:
      - id: check
        env:
          RAW_PLATFORM: ${{ github.event.client_payload.platform }}
          RAW_MODE: ${{ github.event.client_payload.mode }}
          RAW_REF: ${{ github.event.client_payload.ref }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
        run: |
          PLATFORM="${RAW_PLATFORM:-android}"
          MODE="${RAW_MODE:-release}"
          REF="${RAW_REF:-$DEFAULT_BRANCH}"
          case "$PLATFORM" in ios|android|both) ;; *)
            echo "Invalid platform: $PLATFORM" >&2; exit 1;;
          esac
          case "$MODE" in debug|release) ;; *)
            echo "Invalid mode: $MODE" >&2; exit 1;;
          esac
          # Allowlist branches / tags / full SHAs only
          if [[ ! "$REF" =~ ^(main|master|production|release/[A-Za-z0-9._-]+|[0-9a-f]{40})$ ]]; then
            echo "Ref not allowlisted: $REF" >&2
            exit 1
          fi
          if [ "$PLATFORM" = "both" ]; then
            PLATFORMS_JSON='["ios","android"]'
          else
            PLATFORMS_JSON=$(printf '["%s"]' "$PLATFORM")
          fi
          {
            echo "platform=$PLATFORM"
            echo "mode=$MODE"
            echo "ref=$REF"
            echo "platforms_json=$PLATFORMS_JSON"
          } >> "$GITHUB_OUTPUT"


  build:
    needs: validate
    runs-on: ubuntu-latest
    environment: ${{ needs.validate.outputs.mode == 'release' && 'production' || 'build-debug' }}
    strategy:
      fail-fast: false
      matrix:
        platform: ${{ fromJSON(needs.validate.outputs.platforms_json) }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.validate.outputs.ref }}


      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'


      - run: npm ci
      - run: npm run build
      - name: Sync native project
        env:
          PLATFORM: ${{ matrix.platform }}
        run: npx cap sync "$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 }}
          PLATFORM: ${{ matrix.platform }}
          MODE: ${{ needs.validate.outputs.mode }}
        run: |
          npx @capgo/cli@latest build request com.example.app \
            --platform "$PLATFORM" \
            --build-mode "$MODE"

2. GitHub 토큰 만들기

2. GitHub 토큰 만들기

GitHub 앱 설치 토큰이 아닌 개인 접근 토큰을 생성하세요. 저장소에 대한 읽기 및 쓰기 웹훅 호출을 위해 repository_dispatch3. 관리자 대시보드에서 웹훅 호출하기

3. 관리자 대시보드에서 웹훅 호출하기

웹훅 호출을 위해

백엔드 (브라우저가 아닌)는 다음과 같이 보내야합니다:

터미널 창
curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{
    "event_type": "capgo-native-build",
    "client_payload": {
      "platform": "both",
      "mode": "release",
      "ref": "main",
      "requested_by": "admin@example.com"
    }
  }'
Field목적
event_type일치해야합니다. types 워크플로우 (capgo-native-build)
client_payload.platformios, android, 또는 both
client_payload.modedebug or release
client_payload.refBranch 또는 태그를 빌드할 수 있는지 여부 (선택)

your your 백엔드; 백엔드가 가지고 있는 GITHUB_TOKEN.

Option B — 모든 호스트에 가능한 작은 프록시 웹후크

Section titled “Option B — 모든 호스트에 가능한 작은 프록시 웹후크”

관리자 도구가 URL을 제어하는 URL에만 POST할 수 있다면 (Zapier, Make, Cloudflare 워커, Express 경로), GitHub 앞에 짧은 프록시를 두세요:

// Example Cloudflare Worker / Node handler (sketch)
export default {
  async fetch(request, env) {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 })
    }
    if (request.headers.get('x-webhook-secret') !== env.WEBHOOK_SECRET) {
      return new Response('Unauthorized', { status: 401 })
    }
    const body = await request.json().catch(() => ({}))
    const platform = body.platform || 'both'
    const mode = body.mode || 'release'
    const ref = body.ref || 'main'
    if (!['ios', 'android', 'both'].includes(platform)) {
      return new Response('Invalid platform', { status: 400 })
    }
    if (!['debug', 'release'].includes(mode)) {
      return new Response('Invalid mode', { status: 400 })
    }
    if (!/^(main|master|production|release\/[A-Za-z0-9._-]+|[0-9a-f]{40})$/.test(ref)) {
      return new Response('Ref not allowlisted', { status: 400 })
    }
    const res = await fetch(
      `https://api.github.com/repos/${env.GITHUB_OWNER}/${env.GITHUB_REPO}/dispatches`,
      {
        method: 'POST',
        headers: {
          Accept: 'application/vnd.github+json',
          Authorization: `Bearer ${env.GITHUB_TOKEN}`,
          'X-GitHub-Api-Version': '2022-11-28',
        },
        body: JSON.stringify({
          event_type: 'capgo-native-build',
          client_payload: { platform, mode, ref },
        }),
      },
    )
    return new Response(res.status === 204 ? 'Build queued' : await res.text(), {
      status: res.status === 204 ? 200 : res.status,
    })
  },
}

관리자 제품을 구성하세요:

설정값
URLhttps://your-worker.example.com/native-build
메서드POST
헤더x-webhook-secret: <shared secret>
본문{ "platform": "both", "mode": "release" }

웹후크를 관리자 대시보드에 연결하는 일반적인 형태는 다음과 같습니다: 대시보드는 하나의 URL과 하나의 비밀 키를 저장하고 Capgo 자격 증명은 GitHub 액션에 남아 있습니다.

GitLab PipeLine 트리거

GitLab PipeLine 트리거

GitLab은 pipe line 트리거 토큰 natural 웹후크 목표입니다.

# .gitlab-ci.yml fragment
capgo_native_webhook:
  stage: build
  script:
    - npm ci && npm run build
    - npx cap sync "${PLATFORM:-android}"
    - npx @capgo/cli@latest build request com.example.app --platform "${PLATFORM:-android}" --build-mode "${BUILD_MODE:-release}"
  rules:
    - if: '$CI_PIPELINE_SOURCE == "trigger"'

Settings → CI/CD → PipeLine 트리거 토큰 아래에 트리거 토큰을 생성합니다. 트리거 토큰, 그 다음 관리자 백엔드에서:

터미널 창
curl -X POST \
  -F token=$GITLAB_TRIGGER_TOKEN \
  -F ref=main \
  -F "variables[PLATFORM]=android" \
  -F "variables[BUILD_MODE]=release" \
  https://gitlab.com/api/v4/projects/PROJECT_ID/trigger/pipeline

두 플랫폼 모두, 두 개의 트리거를 발동하거나 GitHub 예시와 같은 방식으로 작업을 병렬 행렬로 확장할 수 있습니다.

Bitbucket 및 Azure

Bitbucket 및 Azure
플랫폼웹후크 메커니즘
Bitbucketpipeline 트리거 URL 또는 사용자 지정 pipeline + 앱 비밀번호 POST
Azure DevOpsPipeline run REST API PAT을 사용하여 매뉴얼 PIPELINE을 사용하세요. CI UI에서 트리거

패턴은 동일합니다: 관리자 → 비밀 확인 → 호스트 API → Capgo 빌드 작업

관리자 도구 Payload 체크리스트

관리자 도구 Payload 체크리스트 섹션

대시보드 양식이 빌드되면 최소한 다음을 수집하세요:

  • 플랫폼 — ios / android / 두 가지
  • 모드 — 디버그 (QA) 또는 릴리스 (스토어)
  • Git ref branch 또는 tag을 빌드합니다
  • Actor email 또는 사용자 ID를 위한 감사 로그 (pass through client_payload)

선택 사항: 실행 후 CI가 관리자 API에 다운로드 URL을 전송하도록 하십시오. --output-record / build last-output.

보안

페이지/영역: Enterprise 제품/가격 페이지. 역할: UI 레이블. 표시되는 곳: enterprise.astro 페이지. 메시지 키 `enterprise_hero_security_label` (Enterprise Hero 보안 레이블)
  • 보안 섹션x-webhook-secret웹훅을 인증하는 방법 (
  • 허용 목록 platform, mode, 그리고 ref 프록시와 워크플로우 모두에서 validate 작업 — 처리 client_payload 무결성에 대한 위험을 피하기 위해.
  • 받은 값은 env vars / 작업 출력을 통해 전달하십시오. payload field를 스크립트에 삽입하지 마십시오. run: 스크립트.
  • GitHub/GitLab 토큰은 서버측에서만 유지하십시오.
  • 한 개의 저장소에 대한 토큰을 선호하십시오.
  • Proxy를 제한하십시오. native build는 빌드 시간에 비용이 들 것입니다.
  • 스토어 제출 릴리스에 대해 매핑합니다. release 웹훅은 Capgo Builder에서 GitHub 환경(샘플과 같이)으로 전송하거나 추가 확인 플래그를 체크한 경우에만 필요합니다. validate.
관련 문서
관련 문서 같은 Capgo 빌드 작업, Actions / Pipelines 탭에서 시작되었습니다.
GitHub 액션 설정 인증 정보 내보내기 및 사용하는 비밀 이름
자동 OTA 또는 네이티브 git push 시 live update vs 네이티브를 자동으로 선택하세요.