GitHub Actions
Tuist Runners are currently invite-only. Reach out or ping us in the community Slack to request access for your account.
Running a job on the fleet takes three changes: connect GitHub, point runs-on at a Tuist profile, and push.
-
Connect GitHub. Make sure your project is connected to your GitHub organization. Tuist receives
workflow_jobevents for that organization and dispatches matching jobs to the fleet. Without this connection, no jobs reach your runners. -
Point
runs-onat a Tuist profile. Every enabled account starts with two ready-to-use profiles:linuxandmacos. Reference them with thetuist-prefix:jobs: build: runs-on: tuist-macos # or tuist-linux steps: - uses: actions/checkout@v4 - run: tuist testyamljobs:build:runs-on: tuist-macos # or tuist-linuxsteps:- uses: actions/checkout@v4- run: tuist testSelect Xcode with the runner profileA macOS runner image contains a single Xcode version, which Tuist selects before the job starts based on the profile. If you're migrating from GitHub-hosted runners, remove steps that use
xcode-select --switch(orxcode-select -s) or other tools and actions to switch Xcode versions. Those steps commonly reference Xcode installations specific to GitHub-hosted images and can fail on Tuist Runners.To use another Xcode version, create or choose a profile with that version and update
runs-on, for exampleruns-on: tuist-xcode-26-4.xcodebuild,xcrun, andswiftwill then use the profile's selected Xcode without any additional setup in the workflow. -
Push and watch. The job is queued, claimed by a runner, and streamed back to the Runners section of your Tuist dashboard, where you can follow its logs, steps, and machine metrics.
Cache volumes#
Keep the Xcode, module and Gradle caches and other directories between jobs with cache volumes. Add them after checkout and before the commands that use them.
Grant the job id-token: write so its cache volumes and cached checkout attach as soon as it starts. Without it, the runner waits for GitHub to report which job it is running, and a job GitHub reports late starts with empty caches. A workflow that logs in to Tuist with OpenID Connect already grants it.
permissions:
contents: read
id-token: write