Install the Hex package

Tuist provides a Hex package, tuist_ex, that integrates with your Elixir project to enable features like build insights and test insights. This guide walks you through installing and configuring it.

The package requires Elixir 1.18 or later. It does not need the Tuist command-line interface.

1. Create the project#

Create a project in the Tuist dashboard and choose Mix (Elixir) as its build system. Its handle, account/project, is what connects your Mix project to it.

2. Add the package#

Add tuist_ex to the dependencies in your mix.exs:

elixir

defp deps do
  [
    {:tuist_ex, "~> 0.3", runtime: false}
  ]
end

Then fetch it:

bash

mix deps.get

runtime: false keeps Tuist out of your running application. Continue with Get started with Elixir to configure caching, build insights and test insights together. The sections below cover authentication and configuration details.

3. Authenticate your team and continuous integration#

Each teammate runs the following to get access to the Tuist features on their machine:

bash

mix tuist.login

It opens a browser and waits for you to authorize. To log in without a browser, pass your credentials:

bash

mix tuist.login --email [email protected] --password secret

When you use a self-hosted or local Tuist server, set its base URL in mix.exs, or pass it with --url:

bash

mix tuist.login --url http://localhost:8080

Keep the hostname spelling consistent. For example, a login stored for localhost is separate from one stored for 127.0.0.1.

On GitHub Actions, CircleCI, and Bitrise, continuous integration needs no login step. The first time a task sends a report, it exchanges the provider's OpenID Connect token for a Tuist token. Connect your GitHub repository to your Tuist project, and on GitHub Actions give the job the id-token: write permission:

yaml

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: erlef/setup-beam@v1
        with:
          elixir-version: '1.18'
          otp-version: '27'
      - run: mix deps.get
      - run: mix test

With any other OpenID Connect identity provider, such as Fly.io Machines, configure a workload identity trust policy in the Workload identities section of your account's Settings → Authentication page, which grants CI access to all current and future projects owned by that account. Set TUIST_OIDC_ACCOUNT to the Tuist account that owns the project, and supply a freshly minted identity token with the policy's audience through TUIST_OIDC_TOKEN. The integration exchanges it automatically when no account token or valid stored login is available; mix tuist.login also accepts it outside CI. Automatic exchanges reuse an unexpired session only for the same server, account, and supplied identity token. Changing that identity triggers a new exchange, and a blank supplied identity fails instead of reusing an earlier session. Tuist sessions last one hour without refresh tokens, so for longer-running workloads, mint a new identity token and run mix tuist.login again before the session expires. Follow the workload identity setup and the Fly.io example.

Pull requests from forks don't get an OpenID Connect token, so their runs aren't reported and still pass or fail as usual. On other providers, set the TUIST_TOKEN environment variable to an account token. Follow the continuous integration authentication guide to create one.

4. Keep using `mix test` and `mix compile`#

The shared setup installs the compile and test aliases for you. mix test test/my_app_test.exs:12 --trace reports the run with the same output and exit code, and the compile integration covers builds triggered by mix test or mix phx.server. A compile that finds nothing to do is not reported.

The tasks also work when you call them by their own name. Mix starts a task typed that way in the dev environment, so the task has to start over in a second process for the test environment. Add the tasks to the preferred environments to skip that:

elixir

def cli do
  [preferred_envs: ["tuist.test": :test, "tuist.test.build": :test]]
end

Configuration reference#

The following options are available under tuist in the project options of mix.exs:

Option	Type	Default	Description
`project`	`String`	none (required)	The project identifier in `account/project` format.
`url`	`String`	`"https://tuist.dev"`	The base URL of the Tuist server.
`cache`	`boolean` or keyword list	disabled	Setup enables dependency caching. See Elixir cache for exclusions and extra inputs.
`test_retries`	`integer`	`0`	How many times to retry the tests that failed; see test retries.
`tags`	list of `String`	`[]`	Tags to attach to every build; see custom metadata.
`values`	map	`%{}`	Key-value data to attach to every build.

Environment variables take precedence over mix.exs:

Variable	Description
`TUIST_PROJECT`	The project identifier in `account/project` format.
`TUIST_URL`	The base URL of the Tuist server.
`TUIST_TOKEN`	The token to authenticate with, instead of the stored login.
`TUIST_OIDC_TOKEN`	A freshly minted OpenID Connect identity token, exchanged for a Tuist token. Its audience must be `tuist` for GitHub Actions and Bitrise, or match the project's trust policy for other providers. Used by `mix tuist.login` or as a fallback when no account token or valid stored login is available.
`TUIST_OIDC_ACCOUNT`	The Tuist account handle that owns the project. Required when exchanging a token through a project trust policy. It selects among existing trust policies and does not grant access on its own.
`TUIST_TEST_RETRIES`	How many times to retry the tests that failed.
`TUIST_TAGS`	Comma-separated tags to attach to the build.
`TUIST_VALUES`	Comma-separated `key=value` pairs to attach to the build.
`TUIST_DEBUG`	Set to `1` to print why a report could not be sent.

Reporting never changes the exit code of mix test or mix compile. If a report cannot be sent, the task says nothing unless TUIST_DEBUG=1 is set.

Next steps#

Once the package is installed and configured, you can use:

Dependency caching to reuse compiled dependencies locally and across CI builds.
Build insights to track compile times, warnings, and what holds your builds back.
Test insights to track test performance down to each test.
Flaky tests to detect and track tests that fail intermittently.
Test sharding to split your tests across continuous integration runners.

Install the Hex package

1. Create the project#

2. Add the package#

3. Authenticate your team and continuous integration#

4. Keep using mix test and mix compile#

Configuration reference#

Next steps#

4. Keep using `mix test` and `mix compile`#