Skip to main content

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 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:

20250808-build-log-tool-setup.png

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.

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

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


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: