고객은 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 시크릿으로 설정하세요. 워크플로 파일은 준비된 AI 지시문을 Lovable에 복사해 붙여넣으세요(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 프로젝트 (내보내기 가이드)
- 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/
- 앱의 번들을 업로드할 수 있는 권한이 있는 API 키를 생성하세요
- 키를 한 번 복사하세요. 전체 값은 다시 볼 수 없습니다.
이 키를 비밀번호처럼 취급하세요. Git에 commit하거나 Lovable chat에 붙여넣지 마세요.
2단계 — 추가 CAPGO_TOKEN GitHub에 (유일한 env 단계)
Kuldeep과 레포지토리를 소유한 클라이언트 누구에게나 보내는 단계입니다.
- Lovable이 동기화하는 GitHub 레포지토리를 여세요
- 다음으로 이동: 설정 → Secrets 및 변수 → 액션
- 클릭 새로운 repository 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한 뒤 워크플로우가 재배포되도록 하세요.
암호화된 번들: 사용 중이라면 Capgo 암호화, 다음을 추가하세요 CAPGO_PRIVATE_KEY 두 번째 GitHub secret으로 추가하고 전달하세요. --key-data-v2 "${{ secrets.CAPGO_PRIVATE_KEY }}" upload 단계에서.
4단계 — Publish 확인 시 배포 트리거
- Lovable에서 눈에 보이는 작은 변경을 만드세요 (예: 버튼 라벨 텍스트)
- 클릭 배포
- GitHub에서 열고 액션 지켜보세요 Capgo Live Update
- job이 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 로컬에서 커밋 package-lock.json, 다시 배포 |
| Upload 성공, 흰 화면 | 잘못된 webDir 또는 Vite base |
일치 capacitor.config.ts webDir 빌드 출력(dist Vite용)과 설정 base: './' |
| 사용자가 업데이트를 확인하지 못함 | 채널이 빌드에 연결되지 않음 | Capgo에서 디바이스 빌드를 production 에 연결하거나 채널을 공개로 설정 |
추가 워크플로 패턴(기능 브랜치, PR 채널, 암호화)은 GitHub Actions 연동.
클라이언트에게 전달할 내용
다음 체크리스트를 보내주세요:
- 귀하 이미 Lovable을 GitHub에 연결하고 모바일 앱에 Capgo 설정을 완료했습니다.
- 클라이언트는 GitHub secret 하나를 추가하세요:
CAPGO_TOKENCapgo API 키를 사용하여 (apikeys 페이지). - 클라이언트는 클릭 배포 사용자가 변경 사항을 받기를 원할 때마다 Lovable에서 실행합니다.
- 그들은 절대 실행하지 않습니다
npx @capgo/cli원하지 않는 한 로컬에서는 실행하지 않습니다.
이는 그들이 요청했던 원클릭 경험과 일치합니다. Lovable의 Publish 버튼만 누르면, GitHub Actions와 Capgo이 나머지를 처리합니다.
계속하기
- Lovable을 iOS 및 Android로 변환하기 — 앱을 아직 래핑하지 않았다면 전체 Capacitor + Capgo 설정
- GitHub Actions를 통한 자동 빌드 및 릴리스 — 태그 기반 릴리스 및 버전 업데이트
- GitHub Actions 연동 — 멀티 채널 및 PR 프리뷰 채널
- Capgo Live Update — 채널, 롤백, 도입 통계