Skip to content

Getting Started

In this guide, you will learn how to create your first native build using Capawesome Cloud Native Builds.

Prerequisites

Before you begin, ensure you have:

Step 1: Create an App

To identify your app in Capawesome Cloud, you need to create an app in the console. If you have already created an app, you can skip this step and proceed to Step 2.

To create an app using the Capawesome CLI, use the apps:create command:

npx @capawesome/cli apps:create

You will be prompted to select the organization you want to create the app in and to provide a name for the app. The CLI will then create the app.

To create an app using the Capawesome Cloud Console, select the organization you want to create the app in and click on the "Create App" button.

Step 2: Connect Your Source Code

The most common way to build is by connecting your Git repository to Capawesome Cloud. This lets the build service clone your source code and build your app, and unlocks Git metadata and Automations.

Follow these steps to connect your repository:

  1. Navigate to the Git page of your app in the Capawesome Cloud Console.
  2. In the Git Providers section, select your Git provider (GitHub, GitLab, Bitbucket, etc.) and click Connect to authorize Capawesome Cloud to access your account. If you've already connected a provider, you can skip this step.
  3. In the Git Repositories section, select your Git provider from the dropdown, choose the repository owner, and select the repository you want to connect.
  4. Click Save to finalize the connection.

Your Git repository is now connected to Capawesome Cloud and ready for building.

No Git? Or a Git server behind a firewall?

Connecting Git is optional. You can upload your local source files directly with the CLI's --path option instead — see Build without Git Connection. If your Git server sits behind a firewall, see Access Git Behind a Firewall for your options.

Step 3: Trigger First Build

Once your Git repository is connected, you can trigger your first build.

Use the apps:builds:create command:

npx @capawesome/cli apps:builds:create --platform android --git-ref main
  1. Navigate to the Builds page of your app.
  2. Click Build from Git.
  3. Select the Git reference (branch, tag, or commit) to build from.
  4. Select the Platform (iOS or Android) and Build Type. Choose Debug or Simulator for initial testing.
  5. Click Build to start the build.

Monitor the build until it completes, then download the artifact.

For a quick first build, choose Debug on Android or Simulator on iOS — neither needs a signing certificate. Note that an iOS Simulator build runs only in the iOS Simulator and cannot be installed on a physical iPhone (see Step 4).

Congratulations! You have created your first native build using Capawesome Cloud. 🎉

Step 4: Install Your Build

How you run your build depends on the platform and build type you chose. For full instructions, see Install a Build on a Device.

A Debug APK installs directly on a physical device — no signing required. Open the build's detail page, click Install App, scan the QR code (or tap Download on the device), then open the APK to install. You'll need to allow installs from unknown sources first.

For a Release build, add a signing certificate.

A Simulator build runs only in the iOS Simulator on a Mac — it cannot be installed on a physical iPhone via QR code or download.

To install on a real device, create a signed Development build: register the device's UDID, add an iOS signing certificate and provisioning profile that includes the device, then install via the QR code. See Install a Build on a Device for the full walkthrough.

Bonus: Video Tutorials

Want to see the entire process in action? Check out these video tutorials:

This walkthrough covers the full Android build workflow — from triggering a build from your Git repository to downloading the artifact and testing it on your device.

This walkthrough covers how to create an iOS Simulator build as well as a signed Development build using an Apple developer certificate and provisioning profile.

Next Steps