---
title: Getting Started with Native Builds
description: Create your first native iOS or Android build with Capawesome Cloud. Configure signing, environments, and ship installable artifacts in minutes.
---

# 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:

- A [Capawesome Cloud](https://console.cloud.capawesome.io){:target="_blank"} account and organization.
- An iOS or Android app in a Git repository (Capacitor, Cordova, or native).
- The latest version of the [Capawesome CLI](../cli/index.md) installed and [authenticated](../cli/authentication.md).

## 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.

=== "CLI"

    To create an app using the [Capawesome CLI](../cli/index.md), use the [`apps:create`](../cli/commands.md#appscreate) command:

    ```bash
    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.

=== "Console"

    To create an app using the [Capawesome Cloud Console](https://console.cloud.capawesome.io/organizations/_/apps){:target="_blank"}, select the organization you want to create the app in and click on the "Create app" button.

    <figure>
      <video controls="true" allowfullscreen="true" autoplay="true">
        <source src="/docs/assets/videos/cloud-app-create.mp4" type="video/mp4">
      </video>
    </figure>

## 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](../automations/index.md).

Follow these steps to connect your repository:

1. Create a [Git connection](../integrations/index.md) for your organization on the [Git connections](https://console.cloud.capawesome.io/organizations/_/git){:target="_blank"} page. A connection stores the provider and credentials and can be reused across all apps in your organization. If your organization already has a connection for your provider, you can skip this step.
2. Navigate to the **Git repository** page of your app in the Capawesome Cloud Console, select the Git connection, and choose the repository you want to connect. You can also connect a repository while creating an app or importing from Git.

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

!!! tip "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](build-without-git.md). If your Git server sits behind a firewall, see [Access Git Behind a Firewall](firewall-access.md) for your options.

## Step 3: Trigger First Build

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

=== "CLI"

    Use the [`apps:builds:create`](../cli/commands.md#appsbuildscreate) command:

    ```bash
    npx @capawesome/cli apps:builds:create --platform android --git-ref main
    ```

=== "Console"

    1. Navigate to the [Builds](https://console.cloud.capawesome.io/apps/_/builds){:target="_blank"} 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](monitor-builds.md) 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](certificates/index.md). 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](install-on-device.md).

=== "Android"

    A **Debug** APK installs directly on a physical device — no signing required. Open the build's detail page, click **Install**, 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](install-on-device.md#android) first.

    For a **Release** build, add a [signing certificate](certificates/android.md).

=== "iOS"

    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](certificates/ios.md) and provisioning profile that includes the device, then install via the QR code. See [Install a Build on a Device](install-on-device.md#ios) for the full walkthrough.

## Bonus: Video Tutorials

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

=== "Android"

    <div style="margin-top: 1rem;">
      <iframe width="100%" height="450px" src="https://www.youtube.com/embed/LygUq4BqRs8?si=piRJ6zFccrEQSZls?rel=0&modestbranding=1" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
    </div>

    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.

=== "iOS"

    <div style="margin-top: 1rem;">
      <iframe width="100%" height="450px" src="https://www.youtube.com/embed/7N64zrcNE2M?si=0ulqTcvPGfTnpeyg?rel=0&modestbranding=1" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
    </div>

    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

<div class="grid cards" markdown>

-   :material-shield-key:{ .lg .middle } **Sign Your Builds**

    ---

    Add a signing certificate to produce release builds ready for distribution.

    [:octicons-arrow-right-24: Set up signing certificates](certificates/index.md)

-   :material-rocket-launch:{ .lg .middle } **Submit to the Stores**

    ---

    Send your builds straight to TestFlight and Google Play.

    [:octicons-arrow-right-24: Set up App Store Publishing](../app-store-publishing/setup.md)

-   :material-sync:{ .lg .middle } **Automate Your Builds**

    ---

    Trigger builds automatically on every push or tag.

    [:octicons-arrow-right-24: Set up Automations](../automations/setup.md)

</div>