Skip to content

GitHub Actions

Invite-only

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.

  1. Connect GitHub. Make sure your project is connected to your GitHub organization. Tuist receives workflow_job events for that organization and dispatches matching jobs to the fleet. Without this connection, no jobs reach your runners.

  2. Point runs-on at a Tuist profile. Every enabled account starts with two ready-to-use profiles: linux and macos. Reference them with the tuist- prefix:

    yaml
    jobs:
    build:
    runs-on: tuist-macos # or tuist-linux
    steps:
    - uses: actions/checkout@v4
    - run: tuist test
    Select Xcode with the runner profile

    A 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 (or xcode-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 example runs-on: tuist-xcode-26-4. xcodebuild, xcrun, and swift will then use the profile's selected Xcode without any additional setup in the workflow.

  3. 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.

yaml
permissions:
contents: read
id-token: write