Skip to content

Commit 59eab07

Browse files
WcaleNieWolnyWcaleNieWolny
authored
docs: add introduction page for Capgo Build + explain what gets sent to Capgo build (#434)
* docs: add introduction page for Capgo Build * docs: explain what gets build better + fix false claims
1 parent 637cf08 commit 59eab07

File tree

2 files changed

+177
-10
lines changed

2 files changed

+177
-10
lines changed

‎src/content/docs/docs/cli/cloud-build/getting-started.mdx‎

Lines changed: 50 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ sidebar:
55
order: 1
66
---
77

8-
import { Steps, Card, CardGrid } from '@astrojs/starlight/components';
8+
9+
import { Steps, Card, CardGrid, Aside } from '@astrojs/starlight/components';
910
import MermaidGraph from '@/components/MermaidGraph.astro';
1011

1112
export const buildProcessFlowGraph = `flowchart LR
@@ -170,19 +171,50 @@ iOS builds require signing certificates and provisioning profiles. See [iOS Buil
170171

171172
## What Gets Built
172173

173-
**Important:** Capgo Cloud Build only builds the **native parts** of your app (iOS and Android native code).
174+
Capgo Build only uploads the **minimum files needed** to compile your native app. Your full source code never leaves your machine.
175+
176+
### What Gets Uploaded
177+
178+
| Included | Description |
179+
|----------|-------------|
180+
| `ios/` or `android/` | The native platform folder you're building |
181+
| `package.json`, `package-lock.json` | Dependency manifest |
182+
| `capacitor.config.*` | Capacitor configuration |
183+
| `resources/` | App icons, splash screens |
184+
| Native plugin code | Only the `ios/` or `android/` subfolder of each Capacitor plugin |
185+
186+
### What's NOT Uploaded
187+
188+
| Excluded | Why |
189+
|----------|-----|
190+
| `node_modules/` (most of it) | Only native plugin code is included, not JS dependencies |
191+
| `src/` | Your web source code stays local |
192+
| `dist/`, `www/`, `build/` (root level) | Already synced into the native folder via `cap sync` |
193+
| `.git/` | Version control history |
194+
| `.gradle/`, `.idea/`, `.swiftpm/` | Build caches and IDE settings |
195+
| `.env`, secrets | Never uploaded |
196+
197+
<Aside>
198+
Your built web assets (JS, CSS, HTML) **are** uploaded - but as part of the native folder. When you run `npx cap sync`, your web build is copied into `ios/App/App/public/` or `android/app/src/main/assets/public/`. That's why running `cap sync` before building is required.
199+
</Aside>
200+
201+
### Your Responsibilities
202+
203+
Before running `npx @capgo/cli build`:
174204

175-
You are responsible for:
176-
- Building your web assets (`npm run build`)
177-
- Running `npx cap sync` before the build
178-
- Ensuring all dependencies are in `package.json`
205+
1. **Build your web assets** - Run `npm run build` (or your framework's build command)
206+
2. **Sync to native** - Run `npx cap sync` to copy web assets into the native project
207+
3. **Commit dependencies** - Ensure all native plugins are in `package.json`
208+
209+
### What Capgo Build Handles
179210

180-
We handle:
181211
- Native iOS compilation (Xcode, Fastlane)
182212
- Native Android compilation (Gradle)
183-
- Code signing
213+
- Code signing with your credentials
184214
- App store submission (if configured)
185215

216+
<div style="border-top: 1px solid var(--sl-color-gray-5); margin: 2rem 0;"></div>
217+
186218
## Build Time & Costs
187219

188220
Build time is measured from start to completion:
@@ -224,14 +256,22 @@ npx @capgo/cli@latest build com.example.app \
224256

225257
### Multi-Platform Builds
226258

227-
Build for both platforms simultaneously:
259+
Build for both platforms by running two commands:
228260

229261
```bash
262+
# iOS build
263+
npx @capgo/cli@latest build com.example.app \
264+
--platform ios \
265+
--build-mode release
266+
267+
# Android build
230268
npx @capgo/cli@latest build com.example.app \
231-
--platform both \
269+
--platform android \
232270
--build-mode release
233271
```
234272

273+
In CI/CD, you can run these in parallel jobs for faster builds.
274+
235275
## Next Steps
236276

237277
Now that you've created your first build:

‎src/content/docs/docs/cli/cloud-build/index.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Introduction to Capgo Build
3+
description: Build iOS and Android apps in the cloud without local setup. No Mac required for iOS builds.
4+
sidebar:
5+
order: 0
6+
label: Introduction
7+
---
8+
9+
import { Card, CardGrid, Aside, LinkCard } from '@astrojs/starlight/components';
10+
11+
Capgo Build is a cloud-based native app compilation service for Capacitor apps. It lets you build iOS and Android apps without maintaining local development environments - no Xcode, no Android Studio, no Mac hardware required.
12+
13+
## What Capgo Build Does
14+
15+
Capgo Build compiles the **native parts** of your Capacitor app in the cloud:
16+
17+
- **iOS builds** run on dedicated Apple Silicon (Mac Mini M4) machines
18+
- **Android builds** run in isolated Docker containers
19+
- **Automatic code signing** handles certificates, provisioning profiles, and keystores
20+
- **Direct store submission** uploads signed apps to App Store Connect and Google Play
21+
22+
You trigger builds with a single CLI command that works from anywhere - your local machine, GitHub Actions, GitLab CI, or any CI/CD pipeline.
23+
24+
## When to Use Capgo Build vs Live Updates
25+
26+
Capgo offers two complementary features for updating your app. Here's when to use each:
27+
28+
| Scenario | Live Updates | Capgo Build |
29+
|----------|:------------:|:-----------:|
30+
| Bug fix in JavaScript/TypeScript code | ✓ | |
31+
| UI changes (HTML, CSS, images) | ✓ | |
32+
| Updating web dependencies | ✓ | |
33+
| Adding or removing a Capacitor plugin | | ✓ |
34+
| Updating a native SDK version | | ✓ |
35+
| Changing native permissions (Info.plist, AndroidManifest) | | ✓ |
36+
| Updating Capacitor version | | ✓ |
37+
| Modifying native code (Swift, Kotlin, Java) | | ✓ |
38+
| Changing app icon or splash screen | | ✓ |
39+
| First app store submission | | ✓ |
40+
41+
<Aside>
42+
**Live Updates** push JavaScript changes instantly without app store review. **Capgo Build** creates new native binaries when you change native code. Most teams use Live Updates daily and Capgo Build occasionally when native changes are needed.
43+
</Aside>
44+
45+
## Why Use Capgo Build
46+
47+
<CardGrid>
48+
<Card title="No Mac Required for iOS" icon="laptop">
49+
Build and ship iOS apps without Mac hardware. Anyone on Windows, Linux, or any CI/CD system can trigger iOS builds and publish to TestFlight.
50+
</Card>
51+
52+
<Card title="Skip Local Environment Setup" icon="rocket">
53+
No need to install Xcode, Android Studio, or manage SDK versions. Capgo Build handles all native tooling - you just run the CLI command.
54+
</Card>
55+
56+
<Card title="Centralized Credentials" icon="setting">
57+
Store your certificates and keystores in your CI/CD secrets once. Any team member can trigger builds without needing signing credentials on their local machine.
58+
</Card>
59+
60+
<Card title="Works With Any CI/CD" icon="github">
61+
A single CLI command integrates with any pipeline. GitHub Actions, GitLab CI, Jenkins - trigger builds as part of your existing workflow.
62+
</Card>
63+
64+
<Card title="Real-Time Build Logs" icon="list-format">
65+
Watch your build progress live in your terminal. Logs stream via Server-Sent Events so you can debug issues instantly as they happen.
66+
</Card>
67+
68+
<Card title="Direct Store Submission" icon="approve-check">
69+
Signed apps upload directly to App Store Connect and Google Play. No manual steps between build completion and store submission.
70+
</Card>
71+
</CardGrid>
72+
73+
## How It Works
74+
75+
When you run the build command:
76+
77+
1. **Upload** - The CLI zips only what's needed (native platform folder + native dependencies) and uploads to secure cloud storage
78+
2. **Build** - Your app compiles on dedicated infrastructure using Fastlane
79+
3. **Sign** - Certificates and keystores are applied (they exist only in memory during the build)
80+
4. **Submit** - Signed apps are uploaded directly to App Store Connect or Google Play
81+
5. **Cleanup** - All build artifacts and credentials are automatically deleted
82+
83+
Your source code stays on your machine. Only the platform-specific native code is uploaded.
84+
85+
## Security Model
86+
87+
Capgo Build is designed with zero credential storage:
88+
89+
- **Runtime-only credentials** - Certificates and keystores are never stored in Capgo. They are uploaded and removed immediately after the build finishes.
90+
- **Ephemeral environments** - Each build runs in isolation and is destroyed after completion
91+
- **No log storage** - Build logs stream to your terminal only, never stored on Capgo servers
92+
- **Minimal upload** - Only the native platform you request is uploaded, not your full codebase. [See exactly what gets uploaded](/docs/cli/cloud-build/getting-started/#what-gets-built)
93+
94+
## Pricing
95+
96+
Build time is the only cost:
97+
98+
- Build minutes are included in your Capgo plan
99+
- Extra minutes available via credit system
100+
- iOS builds run on Mac Mini M4 (2x cost multiplier due to hardware costs)
101+
- Android builds run in Docker containers (1x cost)
102+
- No storage fees
103+
104+
## Next Steps
105+
106+
<CardGrid>
107+
<LinkCard
108+
title="Getting Started"
109+
description="Create your first build and see Capgo Build in action."
110+
href="/docs/cli/cloud-build/getting-started/"
111+
/>
112+
<LinkCard
113+
title="Credentials Setup"
114+
description="Configure certificates for iOS and keystores for Android."
115+
href="/docs/cli/cloud-build/credentials/"
116+
/>
117+
<LinkCard
118+
title="iOS Builds"
119+
description="Complete guide to building and submitting iOS apps."
120+
href="/docs/cli/cloud-build/ios/"
121+
/>
122+
<LinkCard
123+
title="Android Builds"
124+
description="Complete guide to building and submitting Android apps."
125+
href="/docs/cli/cloud-build/android/"
126+
/>
127+
</CardGrid>

0 commit comments

Comments
 (0)