Xcode build insights

Working on large projects should not require rebuilding the same code repeatedly. Tuist Build Insights lets you track build analytics so you can identify trends before local and CI build times become bottlenecks.

Build insights are driven by the tuist inspect build command, typically added to your scheme's post-action.

To start tracking local build times, you can leverage the tuist inspect build command by adding it to your scheme's post-action:

You can execute it in that case by setting runPostActionsOnFailure to YES in the relevant project.pbxprojBuildAction:

diff

<BuildAction

buildImplicitDependencies="YES"

parallelizeBuildables="YES"

+ runPostActionsOnFailure="YES">

For Mise, activate tuist in the post-action environment:

For Homebrew, add the Homebrew paths to the post-action environment:

Actor claims are disabled by default. To configure one for a scheme post-action, set TUIST_ACTOR_ID in that script rather than relying on shell exports. Xcode launched from the Dock does not inherit variables from ~/.zshrc. To explicitly suppress a configured claim with Homebrew, use:

With Mise, override the value after Mise loads its environment:

Use an explicit label instead of the empty value to opt in.

Once logged in, local builds are tracked and available from the Tuist dashboard:

Build Insights in CI#

To track build insights on CI, make sure CI is authenticated.

For Xcodebuild-driven CI you need to:

• Use tuist xcodebuild when invoking xcodebuild actions.
• Add -resultBundlePath to your xcodebuild command.

Without -resultBundlePath, required activity logs and result bundles are not generated and tuist inspect build cannot analyze the build.

Machine metrics#

Build insights can include machine-level performance metrics (CPU, memory, network, and disk usage) captured during the build. To enable this, set up a lightweight background daemon that continuously samples system metrics:

This runs a local daemon that samples metrics in the background. The data is picked up automatically by tuist inspect build and uploaded with the build report.

To stop collecting machine metrics, run:

This unloads the daemon's LaunchAgent, removes its plist, and deletes the sampled metrics and daemon logs from ~/.local/state, so nothing is left running in the background.

Report actor claim#

Report-creation requests include the optional x-tuist-actor-id header only when you explicitly set TUIST_ACTOR_ID to an organization-scoped label. No label is sent by default, and Tuist does not detect operating-system usernames.

Labels must be 1–128 bytes of printable ASCII without spaces. An empty or invalid override omits the claim; set TUIST_ACTOR_ID="" to suppress a configured value. The label may contain personal information. Do not use credentials or other sensitive values.

The claim is unverified metadata, not authentication. Existing credentials, permissions, endpoints, and report bodies are unchanged. Servers without actor support ignore the header and keep their existing attribution; this client change alone does not add dashboard actor labels. If a custom proxy rejects unfamiliar headers, opt out using the empty environment override.

Custom metadata#

You can attach metadata to builds with environment variables to improve filtering.

Environment variables#

Examples#

Set these values in CI or your shell before invoking your build: