Troupe Cloud

Builds

Troupe Cloud builds an app from a git ref or an uploaded tarball and keeps the result as an artifact that a device installs or you download. This page covers sources, targets, the expo and xcode presets and their options, logs and artifacts.

How a build runs

1. Probe. A sandbox fetches the source and reads what it is: the commit, the app roots, the frameworks. Nothing of yours runs yet.
2. Plan. A preset turns those facts and your request into a list of typed steps, pinned to the probed commit.
3. Build. A fresh build machine runs the steps and uploads the outputs.
4. Artifact. Troupe computes each output's SHA-256 itself and records it as an artifact.

Start a build

In the web app, open a project and choose Start a build: the repository URL and ref, the platform, the target and the configuration. More options holds the app root, the preset and its options, the timeout and the caches. The build's page then shows its status, its phases, its artifacts and its log as it is written.

Over the API it is builds.create, which needs builds:write. Every role holds it.

curl https://api.troupe.ali.ve/v1/builds/create \
  --header "Authorization: Bearer $TROUPE_API_KEY" \
  --header "Troupe-Contract: 1.0" \
  --header "Content-Type: application/json" \
  --data '{
    "projectId": "prj_…",
    "source": { "kind": "git", "url": "https://github.com/acme/shop", "ref": "main" },
    "osFamily": "ios",
    "target": "simulator"
  }'

The answer is the build, with its buildId (bld_…) and the status queued. Read it again with builds.get until it ends:

until curl --silent "https://api.troupe.ali.ve/v1/builds/get?projectId=prj_…&buildId=bld_…" \
    --header "Authorization: Bearer $TROUPE_API_KEY" |
  jq --exit-status '.build.status | test("succeeded|failed|errored|canceled")' > /dev/null
do sleep 10; done

Sources

A git ref. url is an https:// address the build can read without credentials: no user name or password, no query, no IP address. ref is one of:

A bare name is always a branch, so a tag called main is never built by mistake. A name git would read as something else, such as tags/v1 or HEAD, is refused: write the full ref. Submodules and Git LFS are not supported yet; a request that sets submodules or lfs is refused.

A tarball. For a private repository or a working tree, upload the source. The web app starts builds from a repository only; a tarball build goes through the API:

1. Call builds.create with "source": { "kind": "tarball" }. The build is awaitingSource, and the answer carries an upload session with its uploadId.
2. Call uploads.grant with the uploadId, the name source.tar.gz, the content type application/gzip, the file's size in bytes and its sha256. It returns a signed PUT request: a URL and headers.
3. Send the file with that request.
4. Call uploads.complete. The build moves to queued.

The tarball is a gzipped tar of the source tree, with the tree's root at the archive's root, of at most 2 GiB. The upload must finish within an hour. Uploaded sources are kept for 7 days.

Targets

No preset builds an iOS deviceInternal target yet: such a build fails with target-unsupported.

configuration is release or debug. The expo preset builds release unless you ask otherwise: the JavaScript bundle is embedded, so the app runs with no bundler. debug is offered for the simulator and the emulator and expects a bundler. The xcode preset builds debug by default.

A store or deviceInternal build must say what it signs with: a signing credential's id in signing, or "none". An iOS store build cannot be "none". See Signing credentials.

Presets

A preset recognises a kind of project and knows the steps that build it. Leave preset out and the probe's facts choose one; name it to be sure.

expo

For an Expo app: an app root whose package.json depends on expo. The preset accepts Expo SDK 53 to 58; another SDK fails with sdk-unsupported.

A source without a committed lockfile fails. An emulator build compiles native code for arm64-v8a unless architectures says otherwise.

xcode

For a native iOS app: an Xcode project or workspace in the source, or an XcodeGen spec that generates one. It builds the iOS simulator target only, and is chosen only where the source holds no Expo or React Native app. The build is the project's own xcodebuild: there is no install or CocoaPods step, so a project that uses CocoaPods commits its Pods directory. Swift packages resolve from GitHub.

A React Native app that does not use Expo has no preset yet.

Options

All of these are optional fields of builds.create.

Values in env are never stored or returned: the build keeps only their names, in envNames, and its log masks the values. They can end up inside the app if your project compiles them in. Names the build machine sets itself, such as PATH, HOME, NODE_OPTIONS and JAVA_HOME, are refused.

What a build can reach

A build's network is limited to the hosts its preset lists, on port 443, and the host of its own source.

A dependency from a private registry, or from another host, fails the step that fetches it.

Follow a build

builds.logs replays the log and then follows it, as an event stream:

curl --no-buffer "https://api.troupe.ali.ve/v1/builds/logs?projectId=prj_…&buildId=bld_…" \
  --header "Authorization: Bearer $TROUPE_API_KEY" \
  --header "Accept: text/event-stream"

Each line carries a seq, a time, the step's id, the stream it came from (stdout, stderr, runner or controller) and the text. A follow ends when the build ends, and after 40 minutes at the latest: open it again with since set to the last seq you read. follow=false returns what is there and ends.

When a build fails, failure holds a reason, a message and, when a step failed, its stepId.

builds.cancel ends an unfinished build and stops its machine. builds.list lists a project's builds, newest first.

Artifacts

A finished build names its artifacts in artifactIds. artifacts.list and artifacts.get return each one's format, size and SHA-256 and, where the build read them, the app's bundle id, version, build number and URL schemes, and how it was signed.

• Install it. Name the artifact in install on sessions.create, or in apps.install: { "artifactId": "art_…" }. See installing an app.
• Download it. artifacts.download returns a signed URL that works for 10 minutes.

An artifact is kept for 30 days; its expiresAt says until when. It needs artifacts:read to read or download.

Limits

Build time is metered as build_seconds: see usage.

Next

• Device sessions
• Signing credentials
• Usage and limits
• The builds reference