> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud builds

> Build signed Android and iOS binaries from your GitHub repository, automatically on tags or pushes.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Connect a repository, store signing credentials once, and get signed builds that land straight in your release channels.

## Prerequisites

* A GitHub repository connected through the StackShift GitHub app
* mobile\_build is enabled on the plan

## Workflow

<Steps>
  <Step>
    Create a build profile on the Builds tab: repository, branch, framework (Flutter, React Native, Expo, or native Android), and output (AAB, APK, or IPA).
  </Step>

  <Step>
    Upload your Android signing keystore once; it is encrypted and only ever mounted into the build container as a secret.
  </Step>

  <Step>
    Choose an automatic trigger: every push to the branch, or tags matching a pattern like v\* (recommended).
  </Step>

  <Step>
    Watch build logs live; successful builds are scanned, signed, and land in the internal channel as a release.
  </Step>
</Steps>

## Build profiles

An app can have several named profiles (the default is production), so one app can build Android and iOS, or a staging variant with different environment variables. Pipelines pick a profile by name.

## Where builds run

* Android builds run in an isolated Linux build container with cached Gradle, npm, and pub dependencies per app.
* iOS builds run on hosted macOS infrastructure and deliver signed IPAs the same way.
* Release builds that produce an R8/proguard mapping file upload it automatically so Observe can symbolicate crashes from that version.

## Triggering from CI

Create a CI token with the build:trigger scope and POST to /api/v1/public/mobile/ci/build to start a build from any external system. CI tokens also cover release ingestion, promotion, store submissions, over-the-air publishing, and pipeline dispatch.

## Expected result

<Check>
  Pushing a tag produces a signed, scanned release with version metadata extracted from the binary — no local build machine involved.
</Check>

## Common failures

<Warning>
  * The build cannot sign: no keystore has been uploaded for the app.
  * Tag pushes do not trigger builds: the tag does not match the configured pattern.
  * An iOS profile exists but builds never start: iOS builds run on hosted macOS capacity, which must be enabled for the workspace.
</Warning>