Tuist

Tuist provides shared caching, live run reporting and artifact publication for Once, with application previews for supported native interfaces. Configure the capabilities your project needs independently.

Trigger orchestration is coming

Tuist support for Once triggers is coming. This page covers caching, run reporting and application previews, not CI orchestration.

Create And Connect A Project#

Provision a Tuist project and bind this repository to it in one command:

bash
once connect --provider tuist --create

Once signs you in when needed, creates the project under your personal account, and writes the provider binding into the repository root once.toml. Read Connect A Project for account and project selection. The result is the same configuration described below.

Configure The Cache#

Add a Tuist provider and cache binding to the repository root once.toml:

toml
[infrastructures.tuist] kind = "tuist" account = "acme" project = "app" [infrastructure.cache] provider = "tuist"

Replace acme and app with the Tuist account and project that should own the shared entries.

Authenticate A Developer Machine#

Sign in once:

bash
once auth login --provider tuist

Once reuses the stored session for cache reads, cache writes and artifact publication. Remove it when the machine should no longer access the provider:

bash
once auth logout --provider tuist

Verify A Shared Result#

Use two machines with the same once.toml, script, and input. On the first machine, run the example scripted workflow:

bash
./scripts/greet.sh

The first run reports a cache miss. On a second machine whose local cache has not seen this result, create the same message.txt and run the script again:

bash
printf 'hello from Once\n' > message.txt ./scripts/greet.sh

The second machine should report a cache hit and restore build/greeting.txt. Because its local cache has no matching entry, the hit confirms that Tuist supplied the recorded result.

Publish Application Previews#

Configure Tuist as the artifact publication provider in the repository root once.toml. If the project already defines this provider for caching, reuse that definition and add only the artifact binding:

toml
[infrastructures.tuist] kind = "tuist" account = "acme" project = "application" [infrastructure.artifacts] name = "tuist"
bash
once auth login --provider tuist once artifact publish MyApplication --track review

Tuist receives the full immutable artifact closure through its authenticated project artifact service, not a selected preview payload. The adapter uses existing Tuist authentication and streams content without inspecting native executables. A matching remote receipt confirms publication and returns the project's previews URL. Preview projection happens asynchronously, so this receipt does not mean an application is already available to install.

To publish after successful builds, add an explicit policy and authorize this machine and workspace:

toml
[infrastructure] publish_on_build = ["MyApplication"]
bash
once artifact publish MyApplication --allow-on-build once build MyApplication

All requested builds must succeed, and the producer must approve the entire closure for automatic publication. No artifact-publication request occurs when the policy or local authorization is absent. Authorization binds the exact endpoint and target to Tuist's stable project destination, project:<project_id>. Changing the endpoint, workspace or target requires new authorization; a changed stable destination is rejected before upload. See Artifacts for the provider-neutral policy and replay behavior.

Supported Formats And Limits#

The receiver retains arbitrary artifact payloads and unknown interfaces without executing them. Metadata documents are limited to one mebibyte and the full closure to 20 GiB. Known native interfaces additionally create previews using the project's default preview visibility and existing Tuist distribution surfaces. Generic artifact contents remain private even in public projects:

  • apple_application exports dev.once.apple-install.v2 on macOS, alongside its v1 installation description. The v2 interface points to the bundle ZIP and spec.metadata_payload with once.apple_application.v1 metadata. Ad-hoc signed macOS and simulator applications are eligible for automatic publication and preview projection. Physical-device applications are not.
  • android_binary exports dev.once.android-install.v1, pointing to the APK and spec.metadata_payload with once.android_application.v1 metadata. Debug-signed, non-instrumentation APKs approve automatic publication. Unsigned APKs do not produce installable previews.

Native producers validate signatures and collect metadata; the generic adapter does not. Unknown interfaces remain available through authenticated artifact downloads even when no preview is projected.

The same intent is looked up remotely before transfer. A verified retained receipt avoids another upload; an unconfirmed completion can be recovered by replaying the same intent. Publications expire after 30 days on hosted Tuist, or according to the self-hosted app-preview retention setting. Expired records remain as tombstones and cannot be reactivated by replaying the same intent. The returned URL is not a permanent-byte availability guarantee.

Follow Runs Live#

Once streams build and test runs to Tuist when the provider is configured and the machine is authenticated. Each run publishes ordered event batches to the project's account and project, and the service returns a dashboard link that Once prints as the run starts. Open it to follow the graph, cache decisions, and captured output while the run progresses.

Live reporting is best-effort: a missing endpoint or an expired session is logged and never fails the run. Re-authenticate with once auth login --provider tuist when the session expires.

Authenticate Automation#

Choose the authentication method supported by the environment.

Account Token#

Set TUIST_TOKEN to a Tuist account token authorized for the project's operations when the runner can store a long-lived secret:

bash
TUIST_TOKEN=tuist_... ./scripts/greet.sh

OpenID Connect#

Use OpenID Connect on a supported automation runner. Log in without opening a browser before running cacheable commands:

bash
once auth login --provider tuist --no-browser ./scripts/greet.sh

On GitHub Actions, grant identity-token permission before the login step:

yaml
permissions: id-token: write contents: read steps: - uses: actions/checkout@v6 - run: once auth login --provider tuist --no-browser - run: ./scripts/greet.sh

The resulting session remains available for the rest of the job.

Connection recovery#

Once retries transient cache failures during blob existence checks, uploads, and action-result publication with at most three attempts per RPC. This includes HTTP/2 connection retirement, where the cache asks the client to use a new connection. Interrupted uploads restart from the beginning with a fresh upload resource and a newly opened file or stream.

Authentication failures, permission refusals, invalid requests, quota refusals, requests that exceed the request timeout, and local file errors are not retried, so a cache that stops responding fails after one timeout rather than three. Retries do not provide resumable uploads.

Next#

Add an execution provider when the command should also run away from the current computer. Read Memory to inspect the status, cache state, and action identity that Once records for each run.