GitHub Actions로 Lovable에서 Capgo Live Updates 자동화하기

클라이언트가 Lovable에서 버튼 하나로 모든 활성 사용자에게 변경 사항을 배포하기를 원합니다. 이미 수동으로 업데이트 경로가 작동함을 확인했습니다:

npx @capgo/cli@latest bundle upload --channel=production --auto-bump

필요한 것은 Lovable 내부에서 실행할 또 다른 터미널 명령어가 아닙니다. Lovable은 Publish 시점에 Capgo를 실행할 수 없습니다. GitHub sync가 활성화되었을 때, Publish는 리포지토리에 커밋을 푸시합니다. GitHub Actions가 빌드를 실행하고 bundle upload 를 대신 처리해 줍니다.

이 가이드는 클라이언트가 단 한 번 수행해야 하는 수동 설정인 다음 항목 추가를 다룹니다: CAPGO_TOKEN GitHub secret으로 추가하기. 워크플로우 파일의 경우, 준비된 AI 지침을 Lovable에 복사하여 붙여넣으세요 (Step 3).

파이프라인 작동 방식

단계	대상	프로세스
1	클라이언트	Lovable에서 앱을 수정하고 클릭 배포
2	Lovable	GitHub로 커밋 및 푸시 (보통 `main`)
3	GitHub 작업	`npm ci`, `npm run build`, `bundle upload --auto-bump` Capgo로
4	Capgo	현재 활성화된 기기에서 `production` 채널을 통해 업데이트 수신

SSH, 로컬 CLI, 추가 클릭 없이 시크릿 설정만으로 완료됩니다.

사전 요구사항

GitHub에 연결된 Lovable 프로젝트 (export 가이드)
Capacitor + @capgo/capacitor-updater 레포지토리 내 (Lovable 모바일 전환 가이드)
Capgo에 등록된 앱과 capacitor.config.ts 올바른 위치를 가리키는 appId
production 채널이 존재하고 사용자가 실행하는 빌드와 연결되어 있어야 합니다

이유 `--auto-bump`

모든 Capgo 업로드에는 새로운 고유 bundle 버전이 필요합니다. Lovable Publish는 버전을 올려주지 package.json 않으므로, 동일한 버전을 재사용하면 두 번째 배포에서 CI가 실패합니다.

--auto-bump 채널(또는 앱)의 최신 버전을 읽고 증가시킵니다. 기본 레벨은 minor입니다. 다음을 전달할 수 있습니다 --auto-bump patch 또는 --auto-bump major 원하신다면요.

1단계 — Capgo API 키 생성

열기 console.capgo.app/apikeys/
앱의 번들을 upload할 수 있는 권한을 가진 API 키를 생성하세요
키는 생성 시 한 번만 확인할 수 있습니다. 이후에는 전체 값을 다시 볼 수 없습니다

이 키를 비밀번호처럼 취급하세요. Git에 commit하거나 Lovable chat에 붙여넣지 마세요.

2단계 — 추가 `CAPGO_TOKEN` GitHub에 추가 (유일한 env 단계)

이 단계는 Kuldeep이나 레포지토리 소유자인 클라이언트에게 전달하는 단계입니다.

Lovable이 동기화하는 GitHub repository를 여세요
다음으로 이동: 설정 → Secrets 및 변수 → 액션
클릭 새 레포지토리 Secret
이름: CAPGO_TOKEN
값: 1단계의 Capgo API 키를 붙여넣으세요
저장

GitHub는 해당 secret을 다음으로 workflow에 주입합니다: ${{ secrets.CAPGO_TOKEN }}아래 workflow는 이를 다음으로 읽어옵니다: CAPGO_TOKEN Capgo CLI를 위한 환경 변수

레포지토리가 클라이언트 조직에 속해 있다면, 클라이언트가 해당 레포지토리에 secret을 추가해야 합니다. Lovable 설정이 아니라 GitHub에 있는 키만 있으면 됩니다.

3단계 — 이 프롬프트를 Lovable에 붙여넣기

아래 블록을 Lovable 채팅에 복사하세요. 기본 브랜치가 main이 아니라면, main 워크플로에서 해당 브랜치를 사용 중인 브랜치 이름으로 바꾸세요.

Add Capgo Live Updates CI with GitHub Actions.

Create `.github/workflows/capgo-live-updates.yml` (create folders if needed). Start from this YAML, then adapt install/build to this project while keeping Capgo upload + CAPGO_TOKEN secret behavior:

name: Capgo Live Updates

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Upload bundle to Capgo
        run: npx @capgo/cli@latest bundle upload --channel=production --auto-bump
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Rules:
- Do not hardcode any Capgo API key in the repo or in chat.
- The workflow must read CAPGO_TOKEN only from GitHub Actions secrets (`${{ secrets.CAPGO_TOKEN }}`).
- Keep `--auto-bump` on the upload command so each Publish gets a new unique bundle version.
- Prefer the project's real production build script from package.json (for example `npm run build` or `vite build`).
- If package-lock.json is missing, use `npm install` instead of `npm ci`.
- Do not modify app UI or Capacitor config for this task.
- Commit the workflow file so the next Publish pushes it to GitHub.

Lovable이 변경 사항을 적용한 후, 배포 를 클릭해 워크플로가 GitHub에 반영되도록 하세요.

수동 방식

Lovable 채팅을 사용하고 싶지 않다면, 직접 생성하세요 .github/workflows/capgo-live-updates.yml 이 YAML 파일만 사용하세요(프롬프트 설명 제외). 프로젝트 설정이 다르다면 위 규칙에 따라 install/build 단계를 수정 후 commit 및 push 하세요.

name: Capgo Live Updates

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Upload bundle to Capgo
        run: npx @capgo/cli@latest bundle upload --channel=production --auto-bump
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Vite base 경로: Lovable Vite 앱은 종종 다음이 필요합니다. base: './' 에서 vite.config.ts 그래야 네이티브 쉘 내부에서 에셋이 로드됩니다. OTA 업데이트 후 화이트 스크린이 나타나면 Lovable에 다음 설정을 요청하세요. base: './', 다시 publish 한 뒤 워크플로우가 재배포되도록 하세요.

암호화된 번들: If you use Capgo 암호화, 다음을 추가하세요. CAPGO_PRIVATE_KEY 를 두 번째 GitHub secret으로 추가하고 --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" upload 단계에서.

4단계 — Publish 확인 시 배포 트리거

Lovable에서 눈에 띄는 작은 변경 사항을 만듭니다 (예: 버튼 라벨 텍스트)
클릭 배포
GitHub에서, 액션 확인하며 Capgo Live Updates
작업이 성공(green)하면, Capgo 콘솔을 열고 새로운 bundle이 생성되었는지 확인하세요. production 채널로 이동
앱이 설치된 기기에서 변경 사항이 반영되었는지 확인하세요 (채널 설정에 따라 1분 정도 소요될 수 있음)

✅ 성공: Lovable에서 Publish → 초록색 GitHub Action → Capgo에 새 bundle → 사용자가 업데이트를 받음

문제 해결

증상	예상 원인	해결 방법
Workflow가 실행되지 않음	다음 브랜치가 아닌 브랜치로 Push됨 `main`	변경 사항 `branches` workflow에서 변경하거나 다음으로 publish: `main`
`CAPGO_TOKEN` / 인증 오류	Secret이 누락되었거나 이름이 잘못되었습니다	Secret 이름이 정확히 일치해야 합니다 `CAPGO_TOKEN` Actions secrets 항목에서
이미 존재하는 버전입니다	Upload 시 동일한 bundle 버전을 사용했습니다	유지 `--auto-bump` upload 단계에서 (또는 `--auto-bump patch`)
Build 실패: `npm ci`	Lockfile 동기화 오류	실행 `npm install` 로컬에서 commit `package-lock.json`, 다시 게시
업로드는 성공했지만, 화면이 하얗게 나옴	잘못된 `webDir` 또는 Vite `base`	일치 `capacitor.config.ts` `webDir` 빌드 결과물과 일치하도록 (`dist` Vite의 경우) 설정하고 `base: './'`
사용자에게 업데이트가 보이지 않음	채널이 빌드와 연결되지 않음	Capgo에서 디바이스 빌드를 연결하거나 `production` 채널을 public으로 설정

더 많은 워크플로우 패턴(feature branches, PR channels, encryption)은 다음을 참조하세요: GitHub Actions 연동.

클라이언트에게 전달할 내용

다음 체크리스트를 보내주세요:

귀하 이미 Lovable을 GitHub에 연결하고 모바일 앱에 Capgo 설정을 완료했습니다.
클라이언트는 GitHub secret 하나를 추가해야 합니다: CAPGO_TOKEN Capgo API 키를 사용하여 (apikeys 페이지에서).
클라이언트는 클릭 배포 사용자가 변경 사항을 즉시 받길 원할 때마다 Lovable에서 실행합니다.
원하지 않는 한 npx @capgo/cli 로컬에서 직접 실행할 필요가 없습니다.

이는 그들이 요청한 원클릭 경험과 일치합니다. Lovable의 Publish 버튼만 누르면, GitHub Actions와 Capgo이 나머지를 처리합니다.

계속하기

Lovable을 iOS 및 Android로 변환하기 — 앱을 아직 래핑하지 않았다면, 전체 Capacitor + Capgo 설정 지원
GitHub Actions를 통한 자동 빌드 및 릴리스 — 태그 기반 릴리스 및 버전 업데이트
GitHub Actions 연동 — 멀티 채널 및 PR 프리뷰 채널
Capgo Live Updates — 채널, 롤백, 도입 통계