GitLab CI
Tuist Runners are currently invite-only. Reach out or ping us in the community Slack to request access for your account.
Your pipelines stay in GitLab. Tuist provides an isolated Linux or macOS machine for each job and reports its logs and outcome to GitLab and the Tuist dashboard. GitLab 19.3 or newer is required. GitLab.com and self-managed instances reachable over public HTTPS are supported.
-
Create a GitLab runner. In your project's Settings → CI/CD → Runners, create a project runner. You can also use a group runner. Add all the Tuist profile labels you want to use as runner tags, for example
tuist-linuxandtuist-macos, and disable Run untagged jobs. Keep the authentication token GitLab shows, which starts withglrt-. You do not need to install a runner on your own machine. -
Connect once in Tuist. In Settings → Integrations, choose Connect on the GitLab CI card. Enter your GitLab URL and runner authentication token. The connection can serve jobs using different profiles. Tokens are stored encrypted and are never displayed again. Optionally, add an API access token so that merge request pipelines can save cache volumes; see Merge request pipelines.
-
Choose the machine in each job. Set exactly one Tuist profile label in the job's
tags. Other tags are allowed, provided the registered GitLab runner also has them:# .gitlab-ci.yml linux-check: tags: [tuist-linux] script: - uname -a test: tags: [tuist-macos] script: - tuist test retry: max: 2 when: runner_system_failureyaml# .gitlab-ci.ymllinux-check:tags: [tuist-linux]script:- uname -atest:tags: [tuist-macos]script:- tuist testretry:max: 2when: runner_system_failure -
Push and watch. Tuist starts polling within a minute. Jobs appear under Runners, with a link back to the GitLab job, logs and machine metrics. GitLab receives logs while the job runs; Tuist receives the masked log when it finishes.
Tuist reads CI_JOB_TAGS from each assignment and resolves the profile within the connected Tuist account. It does not infer the machine from CI_RUNNER_TAGS or use a default profile. Missing, unknown, or multiple Tuist profile tags fail the acquired job with an explanation in its GitLab log. Do not override CI_JOB_TAGS in your pipeline variables.
Execution environment#
Jobs use GitLab's shell executor inside an isolated machine. Checkout, CI variables, before_script, script, after_script, artifacts and cancellation are handled by GitLab Runner. The pipeline's image: and services: settings do not configure this shell environment; use tools installed on the runner image or install them in your script.
The reusable runner authentication token stays on the Tuist server. Machines receive credentials for their assigned job only. Cache-signing grants are currently withheld for GitLab jobs. Custom Linux cache volumes verify job identity and save permission through GitLab’s API; overridable CI variables do not establish trust.
GitLab marks a job as running, and starts its timeout, as soon as Tuist acquires it. While the jobs Tuist has already acquired use up your account's concurrency limit, further jobs stay pending in GitLab. An acquired job waits for a machine for up to its job timeout, at most 12 hours. If no machine becomes available by then, Tuist fails the assignment with runner_system_failure, and the retry policy above lets GitLab retry it. The same policy covers a lost runner machine.
Rotating tokens and disconnecting#
Update the connection's tokens and choose Save changes to rotate them. Leaving a token blank preserves the existing credential.
Disconnect stops acquisition and fails waiting assignments. Running jobs continue with their own credentials. If GitLab cannot be reached, Tuist retains the disabled connection while retrying the cancellation of waiting assignments. The connection is removed once those assignments have settled.
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.
Merge request pipelines#
Push, schedule and web pipelines of the project save their changes to cache volumes. Merge request pipelines use the cache, and save their changes only when the connection has an API access token:
- In GitLab, create a project or group access token with the Reporter role and the
read_apiscope. A group token covers every project in the group that runs on Tuist runners. - In Settings → Integrations, paste it into API access token on the GitLab CI card and choose Save changes.
Tuist then reads each merge request pipeline's merge request. Pipelines of merge requests opened from a branch of the project itself save their changes under the merge request's source branch, so the runner profile's branch settings apply to that branch. Merge requests from forks never save. If Tuist can't read the merge request, the job still runs and uses the cache, but its changes are discarded.