Configuring tool versions

Abstract

Bitrise can automatically set up any tools with the right version for your CI project. For example, most CI workflows often start with installing the right version of Ruby or Node.js that is compatible with the project.

Bitrise offers a simple and declarative way to set up tools for the CI/CD environment only. To declare a tool, you just have to add your tool and its version to the tools property on the top level of your configuration YAML file:

tools:
  nodejs: 22:latest
  ruby: 3.3:installed
  golang: 1.24.5

workflows:
# ...

When running a build, tool setup is executed before the first Step of the Workflow. You can see it in a build log:

Defining version numbers

There are three ways to define version numbers for the tools you want to set up at the start of a build:

Set exact version numbers.
Set partial version numbers.
Use special aliases.

Setting exact version numbers

You can define an exact version number in your tools property:

tools:
  nodejs: 22.1.0

This provides the most deterministic behavior and reproducible builds, but installs could take a long time.

Setting partial version numbers

If your project doesn't require precise tool versions, you can define partial version numbers. With a partial version version number, Bitrise will check for either a version preinstalled on the Bitrise build machines or the latest released version available.

For a preinstalled version of a tool, use the x.y:installed syntax:

tools:
  ruby: 3.3:installed

This checks which Ruby 3.3 patch version is preinstalled on the Bitrise build machines and uses that version. If no preinstalled version matches the partial version, the highest matching version is going to be downloaded and installed at runtime. It will not result in a build failure.

For the latest released version of a tool, use the x.y:latest syntax:

tools:
  ruby: 3.3:latest

This installs the latest 3.3 patch version of Ruby, regardless of what is preinstalled on the Bitrise build machines.

Workflow-specific definitions

You can define tool version definitions globally or for one or more Workflows specifically. Instead of defining the tools property at the top level of the configuration, you nest it under one or more Workflows.

You can also unset some tools for certain Workflows with the keyword unset. Unsetting means that tool won't be installed for that Workflow. Unsetting has no effect in the global context.

We recommend using one of three common patterns when using Workflow-specific definitions:

Workflow-specific definitions only:
```
workflows:
  test:
    tools:
      nodejs: 22:installed
```
In this example, the test Workflow uses the highest preinstalled version of Node.js v22. No global tool definitions are set.
Override the global definition in one or more Workflows:
```
tools:
  nodejs: 22:installed
  ruby: 3.3:installed

workflows:
  test-latest-node:
    tools:
      nodejs: "24.7.0"
```
In this example, the global setting is the highest preinstalled version of Node.js v22. The Workflow test-latest-node, however, uses Node.js version 24.7.0.

Unset global tool versions in one or more Workflows:

tools:
  nodejs: 22:installed
  ruby: 3.3:installed

workflows:
  lint:
    tools:
      ruby: unset # this workflow only needs Node.js

In this example, the Workflow called lint won't have Ruby installed.

Using other aliases

It’s also possible to use the special latest and installed version strings to select the highest released or highest installed version of a tool:

The installed value means using the highest installed version at the time of build:

tools:
  ruby: installed

The latest value means using the highest released version at the time of build:

tools:
  nodejs: latest

Supported tools

The system is designed to support a growing list of tools and languages, but Bitrise only verifies and tests the stability of the most common tools listed. If you need a tool not listed here, read more how to use community plugins.

Other tools

If you don’t find a tool listed on this page, you can use community plugins to perform the tool setup. If a community asdf plugin exists for the given tool, you can provide the tool-plugin’s git clone URL in the config. For example, this is how you set up the right version of Deno using its asdf plugin:

tools:
  deno: 2.4.3

tool_config:
  extra_plugins:
    deno: https://github.com/asdf-community/asdf-deno.git

Table 1. Supported tools

Tool name	YAML example	Notes
Ruby	Using a 3.3.x version, preferring a preinstalled version to save install time: tools: ruby: 3.3:installed	At the moment, Ruby versions have to be built from source using the ruby-build project, so each install adds a few minutes to each build. Bitrise stacks come with multiple preinstalled Ruby versions at all times, so you can avoid the install time by using a partial version that uses a preinstalled Ruby (if available).
Go	Installing the 1.24.0 version: tools: golang: 1.24.0
Python	Using a 3.12.x version, preferring a preinstalled version to save install time: tools: python: 3.12:installed	At the moment, Python versions have to be built from source, so each install adds a few minutes to each build. Bitrise stacks come with a preinstalled Python version at all times, so you can avoid the install time by using a partial version that uses a preinstalled Python (if available).
Node.js	Using a 22.x.y version, preferring a preinstalled version to save install time: tools: nodejs: 22:installed
Java	Installing Java 25: tools: java: openjdk-25.0.0
Flutter	Flutter versions need to include the release channel as a suffix: tools: flutter: 3.32.5-stable
Tuist	Installing the 4.54.0 version: tools: tuist: 4.54.0

Changing tool version managers

Bitrise uses tool version managers to install and provide the required tool at runtime. The primary manager is mise, but asdf is also supported and behaves the same. If you want to switch implementations for any reason, you can do so:

tool_config:
  provider: asdf

Limitations and alternatives

No visual editor: This feature is configurable only in configuration YAML for now.
No workflow-level customization: For now, there is only a single global configuration of tools. This applies to all Workflows and Pipelines. We are planning to introduce Workflow-scoped configurations in the future, just like how environment variables can be defined both globally and on the Workflow level.
No access to version files like .node-version or .tool-versions: This feature is meant to setup the CI/CD environment only (for now). If you commit a tool version file to git and want to keep the CI and the local developer environment in sync, you might want to use a version manager like Mise, asdf or nvm in both environments.

In this section: