Run

Tuist runners execute GitHub Actions jobs on managed macOS and Linux continuous integration infrastructure. You can adopt them independently of project generation, then connect caching and insights when you want build work and data shared across developer machines and runners.

Tuist builds runners, caching, and insights as parts of the same infrastructure instead of treating them as separate services. Managed runners are colocated with the Tuist cache infrastructure they use, which shortens the path that build artifacts travel and reduces the latency of cache downloads and uploads.

Keep compute close to build work#

Build automations can move a large volume of compiled artifacts. When compute and cache storage are far apart, part of the time saved by a cache hit can be lost while those artifacts travel across the network. Colocating the runners and cache reduces that overhead, which makes cached work available to the build sooner.

The same Tuist project connects runner jobs and developer machines to shared build work. A successful build on the main branch can populate the cache, then later runner jobs and developer builds can reuse those results instead of compiling them again. This is especially valuable for larger Xcode and Gradle projects, where avoiding repeated compilation has a greater effect on feedback time.

Co-location improves artifact transfer performance, while the cache strategy determines how much work can be reused. Follow the Optimize path to choose between module caching, Xcode compilation caching, and Gradle caching. Use the Observe path to compare cache activity and build duration before and after moving the automation.

Adoption steps#

1. Choose the Tuist account that will own the runner profiles and the project that will connect to the GitHub organization.

2. Follow the runner getting-started guide to connect the project to its GitHub organization.

3. Start with the default macos or linux profile. To choose a different machine size or Xcode version, create a named profile with the runner profiles guide.

4. Change a workflow job's runs-on value:

   yaml

   jobs:

   build:

   runs-on: tuist-macos

   steps:

   - uses: actions/checkout@v4

   - run: tuist test

5. Remove workflow steps that switch Xcode versions. A macOS runner profile selects the Xcode image before the job starts.

6. Push the workflow change and open the Runners section of the Tuist dashboard.

Verify your setup#

Confirm all of the following on the first workflow run:

• GitHub assigns the job to the tuist-macos or tuist-linux label instead of a GitHub-hosted runner.
• The job leaves the queue, completes its checkout and build steps, and reports its final status to GitHub Actions.
• The Tuist dashboard shows the run, step logs, and machine metrics.
• On macOS, xcodebuild -version reports the Xcode version selected by the profile.

After the first job succeeds, evaluate machine shapes and account concurrency limits with representative workloads. Connect the relevant cache so builds on the main branch can populate reusable work for later jobs and developer machines. Then use build insights to confirm that cache activity and colocated infrastructure are reducing the duration of the automation before increasing machine capacity.