Webhook으로 Native Build 실행

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

Capgo Build는 보통 노트북이나 CI job에서 시작됩니다. 관리자 대시보드, CMS 또는 내부 포털에서 배포하는 팀은 보통 단일 HTTP webhook을 선호합니다. 즉, 자체 UI에서 버튼을 누르면 서명된 Native Build가 시작됩니다. 이 가이드에서는 code 호스트로 인증된 간단한 HTTP 호출을 보내, 이미 사용 중인 Capgo Build 워크플로우를 그대로 실행하는 표준 패턴을 설명합니다.

아키텍처

sequenceDiagram
  participant Admin as Admin dashboard
  participant Hook as Webhook endpoint
  participant CI as GitHub / GitLab
  participant Capgo as Capgo Build

  Admin->>Hook: POST /native-build (secret)
  Hook->>CI: repository_dispatch / pipeline trigger
  CI->>CI: checkout, npm ci, cap sync
  CI->>Capgo: build request
  Capgo-->>CI: signed binary / store upload

직접 수행 하지 마세요 공개 “build webhook”을 노출하려면 Capgo이 필요합니다. CI에는 이미 서명 비밀키(signing secrets)가 있으므로, 웹훅의 역할은 해당 CI 작업을 안전하게 시작하는 것입니다.

사전 요구사항

이미 작동 중인 Capgo Build 워크플로우를 CI UI 또는 push 시 실행하도록 설정하려면 (GitHub 작업)
세분화된 GitHub token, GitLab trigger token 또는 이와 유사한 권한이 필요합니다.
관리자 대시보드에서 전송할 공유 secret (header 또는 body)

옵션 A — GitHub `repository_dispatch` (권장)

GitHub는 워크플로우를 시작하는 인증된 API 호출을 수락하며, 이후 다음을 대기합니다. repository_dispatch. JSON을 지원하는 모든 대시보드에서 POST 웹훅을 호출할 수 있습니다.

1. 웹훅을 수신하는 워크플로우

페이로드 검증 첫 번째 제출이 승인되기 체크아웃 후 및 보안 정보가 포함된 단계 이전에 수행하세요. 승인된 값은 job outputs 또는 env vars를 통해 전달해야 하며, 절대 직접 client_payload 다음 항목에 삽입하지 마세요: run: 스크립트 (스크립트 인젝션 방지 가이드).

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 토큰 생성하기

다음 권한을 가진 세분화된 개인 액세스 토큰(또는 GitHub App 설치 토큰)을 생성하세요: 내용: Read and write 리포지토리에 (다음 항목에 필요함) repository_dispatch). 토큰은 관리자 백엔드에만 저장하고, 브라우저에는 절대 노출하지 마세요.

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"
    }
  }'

필드	목적
`event_type`	일치해야 함 `types` 워크플로에서 (`capgo-native-build`)
`client_payload.platform`	`ios`, `android`, 또는 `both`
`client_payload.mode`	`debug` 또는 `release`
`client_payload.ref`	빌드할 브랜치 또는 태그 (선택 사항)

관리자 UI의 버튼(“Build native apps”)에 동일한 JSON POST를 연결하세요. 대시보드는 다음에만 접근하면 됩니다 여러분의 백엔드; 백엔드가 보관합니다 GITHUB_TOKEN.

옵션 B — 간단한 프록시 웹훅 (호스트 무관)

관리자 도구가 직접 제어하는 URL(Zapier, Make, Cloudflare Worker, Express route)로만 POST할 수 있다면, 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,
    })
  },
}

그런 다음 관리 제품을 설정하세요:

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

웹훅을 관리자 대시보드에 연결할 때 흔히 쓰는 구성입니다. 대시보드에는 URL 하나와 secret 하나만 저장하고, Capgo 자격 증명은 GitHub Actions에 그대로 둡니다.

GitLab Pipeline 트리거

GitLab은 다음을 제공합니다: pipeline 트리거 토큰 이 토큰은 webhook 타겟으로 사용하기에 매우 적합합니다.

# .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"'

먼저 다음 경로에서 trigger token을 생성하세요: 설정 → 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

두 플랫폼 모두, 두 개의 trigger를 실행하거나 GitHub 예시와 동일하게 job을 parallel matrix로 확장하세요.

Bitbucket 및 Azure

플랫폼	Webhook 메커니즘
Bitbucket	Pipeline 트리거 URL 또는 커스텀 pipeline + app password `POST`
Azure DevOps	PAT를 사용한 Pipeline run REST API PAT를 사용하세요. 다음에서 수동 pipeline을 사용합니다: CI UI에서 트리거

패턴은 동일합니다: admin → secret 확인 → host API → Capgo Build 작업.

관리 도구용 페이로드 체크리스트

대시보드 폼 구축 시, 최소한 다음 항목을 수집해야 합니다:

플랫폼 — iOS / Android / 둘 다
모드 — debug (QA) 또는 release (store)
Git ref — 빌드할 branch 또는 tag
Actor — 감사 로그용 email 또는 user id (전달) client_payload)

선택 사항: 실행 후, CI가 다운로드 URL을 포함하여 관리자 API로 포스트백을 보냅니다. --output-record / build last-output.

보안

모든 webhook 인증 (x-webhook-secret, HMAC 서명 또는 mTLS).
Allowlist 설정 platform, mode, 그리고 ref 프록시와 워크플로우 모두에 validate job 적용 — client_payload 신뢰할 수 없는 입력값으로 취급하세요.
승인된 값은 env vars / job outputs를 통해 전달하세요. 페이로드 필드를 run: scripts.
GitHub/GitLab 토큰은 서버 측에만 보관하세요.
단일 저장소에만 권한이 제한된 토큰을 사용하세요.
프록시에 Rate-limit를 설정하세요. Native Build는 빌드 시간을 소모합니다.
스토어 제출용 릴리스의 경우, release 샘플과 같이 보호된 GitHub 환경에 매핑하거나, 추가 확인 플래그를 validate.

CI UI에서 트리거 Actions / Pipelines 탭에서 시작되는 동일한 Capgo Build 작업에서 체크하도록 설정하세요.

GitHub Actions 설정 이 워크플로우에서 사용하는 Credential export 및 secret 이름입니다.

자동 OTA 또는 Native git push 시, live update와 native 중 하나를 자동으로 선택합니다.