Evolving Tuist's authentication

Announcements
1

TL;DR

If you are using project tokens on your CI, move to either account or OIDC tokens based on the following docs. Project tokens are deprecated and will be eventually removed. We will send out a notice before removing them, with project tokens being supported at least until June 2026, but we recommend going ahead and migrating away from project tokens now.

Why we’re evolving our authentication

For a long time, our authentication was simple as the needs were simple.

There were two ways to authenticate:

  • as a user via the tuist auth login command, upon which we would store a JWT access and refresh pair. This way of authenticating is here to stay.
  • as a project by creating a project token and including it as a TUIST_CONFIG_TOKEN environment variable, typically used on CI

But as we added more features and more organizations onboarded onto Tuist, it became clear we were starting to outgrow project tokens.

The biggest issue was that on the server, we decided what the project token would have access to – where we allowed any operations that made sense to be used on the CI, like writing to a cache or uploading test results. But then some organizations wanted to start managing their members using a single token or update their account. We didn’t want to include such permissions in the project token for everyone.

Additionally, the project tokens had no expiry and rotating project tokens meant going to each project using Tuist and updating its value. Not great. Let’s go over how we’re evolving our authentication model.

Moving to account and OIDC tokens

To ensure teams can automate their workflows by having access to the full breadth of our API, we introduced account tokens. When creating an account token, you can specify which scopes the token should have access to – and to which projects for project-related scopes. For example, to create a project token that can write cache to all of your projects, expiring in one year, you could run:

tuist account tokens create my-account \
  --scopes project:cache:write \
  --name cache \
  --expires 1y

Scopes relate to individual domains of the data Tuist has access to. For the full list of scopes, see our documentation.

Or if you want to limit it to a specific set of projects:

tuist account tokens create my-account \
  --scopes project:cache:write \
  --name cache \
  --projects my-project
  --expires 1y

The account tokens might remind you of GitHub’s tokens with fine-grained permissions. And, indeed, we took a lot of inspiration from that model.

However, we still wanted to keep the convenience of having a token with permissions defined in the Tuist server that would automatically get access to new scopes that would be typically be useful in CI workflows. To do that, we introduced a ci scope group that is the most direct replacement of project tokens:

tuist account tokens create my-account \
  --scopes ci \
  --name ci \
  --expires 1y

But for supported CI providers, an even better option are OIDC tokens. OIDC tokens allow you to authenticate using a short-lived token that gets generated in each job. CI providers generate a token that Tuist then validates to give you access to the API.

To move to OIDC tokens, you will need to:

  • integrate with GitHub
  • run tuist auth login instead of using the TUIST_TOKEN
  • in case of GitHub Actions, add id-token: write permission

For the exact setup, see our documentation.

We currently support GitHub Actions, CircleCI, and Bitrise. We plan to add support for GitLab in the future (not just for OIDC tokens, but also for other features, like PR comments).

If you’d like to see support for other CI providers, you can let us know below :backhand_index_pointing_down: The same goes for any feedback you might have :relieved_face: