Documentation
How GitHub access works
Sign-in is identity only. The CapWrap GitHub App is how repositories are read and how Actions are started.
Two different GitHub relationships exist. Mixing them up is the usual “CapWrap can’t see my repo” problem.
1. Sign-in (identity)
Continue with GitHub (or Google) creates your CapWrap user. If you pick GitHub, that OAuth login is identity only. It is not enough to list private repos or start workflows.
2. GitHub App (repository access)
Add app installs a GitHub App named CapWrap on the accounts you choose. You pick All repositories or Only select repositories. You can change that later under GitHub → Settings → Applications → Installed GitHub Apps.
After install, GitHub sends you back to CapWrap’s connect screen. CapWrap then uses a short-lived installation token (created on the server) to talk to GitHub. The private key never sits in your browser.
What CapWrap is allowed to do
On repos you granted:
| Permission | Why |
|---|---|
| Read metadata | Know the repo exists |
| Read & write contents | List commits, detect Capacitor, add wrap / pipeline files |
| Read & write pull requests | Open wrap, dependency, and pipeline PRs; merge wrap PRs if you confirm |
| Read & write Actions | Start (workflow_dispatch) the native / preview jobs |
| Read & write Workflows (optional) | Add the Capacitor init workflow that generates ios/ and android/ in CI |
If Workflows permission is missing, the wrap PR still lands — you (or Lovable) run npx cap add ios / android yourselves.
What CapWrap writes
CapWrap prefers a pull request so you can review the diff. Branches you may see:
capwrap/add-capacitor— Capacitor wrapcapwrap/native-pipeline— store pipeline filescapwrap/capacitor-deps— package upgrades
You can tick commit to the default branch for wrap or pipeline if you want to skip the PR. Dependency upgrades always use a PR.
What GitHub tells CapWrap
When the GitHub App webhook is active, GitHub notifies CapWrap about:
- App installed / repos added or removed
- Pushes (new commits on the default branch)
- Workflow runs (success / failed / cancelled)
- Pull requests CapWrap opened
The dashboard can still poll GitHub if you have the page open. Webhooks make status show up without sitting on the page.
GitHub Actions minutes
iOS jobs use GitHub-hosted macOS runners. Those minutes are billed by GitHub on your account / org, not by CapWrap. Android uses Linux runners (cheaper). CapWrap does not sell Mac hardware.
Private GitHub Free accounts have a monthly Actions minutes cap. If a job is queued forever, check GitHub Billing → Actions.