New tool setup CLI: use your existing version files in CI

Changelog Stacks
1

If you’re managing tool versions like Node.js or Ruby in your project, you’ve probably been maintaining them in two places: once in your .node-version or .tool-versions file for local development, and again in your bitrise.yml for CI. Every time you bump a version, you’re updating both files.

The new bitrise tools command lets you skip the duplication and use your existing version files directly in your workflows.

What this solves

Previously, the only way to set up tools in Bitrise workflows was through declarative configuration in bitrise.yml:

tools:
  nodejs: 20.0.0
  ruby: 3.3.0

workflows: ...

But if your project already had a .tool-versions or .node-version file, you were maintaining the same version numbers in two places. Update Node.js locally? Don’t forget to update bitrise.yml too.

What you can do now

With the new bitrise tools command, you can reference your existing version files directly from workflow steps:

workflows:
  build:
    steps:
      - git-clone: {}
      - script:
          inputs:
            - content: bitrise tools setup --config .tool-versions
      # That's it - subsequent steps now have the right tool versions

Alternatively, you can use our new step, which wraps the CLI and provides easier configuration:

workflows:
  build:
    steps:
      - git-clone: {}
      - dependency-installer@1:
          inputs:
            - tool_version_file: ./.tool-versions

Now when you update tool versions in your repository, your CI workflows automatically pick them up. There is one source of truth for versions across CI and the local dev env.

The command works with:

  • .tool-versions (asdf/mise format)
  • Individual version files like .node-version, .ruby-version, etc.
  • Your bitrise.yml file (if you prefer to keep using it)

When no file is provided as --config, it will look for supported version files in the current directory.

Available commands

The CLI includes several subcommands for different use cases. Here are the main ones:

bitrise tools setup - Install tools from version files

bitrise tools setup --config .tool-versions

bitrise tools install - Install a specific tool version on the fly

bitrise tools install nodejs 22:latest
bitrise tools install ruby 3.3.0

bitrise tools latest - Check what’s the latest version available

bitrise tools latest nodejs
bitrise tools latest python 3.12

bitrise tools info - Run this in a script to see what’s installed and active

bitrise tools info --active

Using tools in the same script

Here’s something to watch out for: by default, tools you install become available in subsequent workflow steps, but not in the same script where you install them.

# This won't work as expected
bitrise tools setup --config .ruby-version
ruby --version  # Still sees the old Ruby version

If you need tools immediately in the same script, use the --format bash flag with eval:

# This works
eval "$(bitrise tools setup --config .ruby-version --format bash)"
ruby --version  # Now sees the newly installed version

The bash format outputs shell export statements that update your $PATH and other environment variables. The eval makes those changes take effect in your current shell session.

Comparison with declarative setup

Both the new CLI approach and the existing declarative setup have their place. Here’s how they compare:

Aspect Declarative (bitrise.yml) CLI (bitrise tools)
Execution timing Automatic before first workflow step Manual, can run at any point in workflow
Config location Must be in bitrise.yml Can read from version files in repository
Use case Easy to get started, declarative Projects with existing tool version files, custom setup logic

For more details on supported tools, version syntax options, and advanced configuration, check out the full documentation.

Let us know if you run into any issues or have feedback. Happy building! :wave:

1 Like