Rakko

Use a Toolchain From an Action

Run your action on the compiler or runtime that the project pins. Require a release of it only when an older release gives a wrong result.

Run your action on a toolchain of the project, such as Node.js or Rust. The project pins its toolchains, and your action runs on that pin. Your action can also require some releases of a toolchain, when another release gives a wrong result.

This guide builds test-node, an action that runs the test runner of Node.js on a project. You need to know how to build an action. The action uses rakko-tool, as in Run a Tool From an Action.

The Pin of a Toolchain

A toolchain is a compiler or runtime that the code of the project builds or runs with. The project pins it in its own mise.toml:

[tools]
node = "24.11.0"

Your action does not pin a toolchain, and doctor --fix never writes or changes the pin of a toolchain. A project that updates Node.js changes its own pin, and your action then runs on the new release.

A tool is different. Your action pins each tool that it wraps, such as taplo, in its mise.rakko.toml, and its tests cover that version. Tools and Mise explains why the two have different owners.

Resolve the Toolchain

Resolve the toolchain with Tool::resolve_toolchain. Give it the program to start:

async fn run(&self, context: &Context, _args: &Self::Args) -> Outcome {
    let node = match Tool::resolve_toolchain()
        .action(self)
        .toolchain("node")
        .executable("node")
        .context(context)
        .call()
        .await
    {
        Ok(node) => node,
        Err(error) => {
            return Outcome::Errored {
                source: Box::new(error),
            };
        }
    };

    let execution = match node
        .invocation()
        .arg("--test")
        .launch_with(context.tool_output(), ShownStreams::Both)
        .await
    {
        Ok(execution) => execution,
        Err(error) => {
            return Outcome::Errored {
                source: Box::new(error),
            };
        }
    };

    if execution.status().success() {
        return Outcome::Passed { summary: None };
    }

    // This example reports every other exit as a failed test, also a
    // crash of Node. An action for real projects reads the report of the
    // test runner, and gives one finding for each test that failed.
    let report = execution.stdout().to_string_lossy();

    Outcome::Failed {
        findings: vec![
            Finding::builder()
                .message(report.trim())
                .location(Location::Project)
                .build(),
        ],
        repairs: Vec::new(),
    }
}

The lookup asks mise for the program at the version that the project pins. It never searches the PATH of the environment. So your action runs on the same release as the editors, the terminals, and the CI of the project. A project that pins no Node.js stops the action with an error that says so.

Without a requirement, the lookup takes the first pin of the toolchain. With one, it takes the first pin that the requirement accepts. A project can pin several releases of one toolchain, as it does for a stable and a nightly release of Rust. An action that needs another pin selects it in the run, such as the release that the rust-version of a manifest gives. accepting adds such a range for one lookup.

Some tools start their toolchain by name, such as a package for Node.js that starts node. Resolve the tool and the toolchain. Then give the toolchain to the tool with Tool::with_toolchain. The tool then runs on the toolchain of the project, and not on the one that comes first on the PATH.

Require a Release

Most actions require nothing of a toolchain, and they run on whatever release the project pins. An action without a requirement does not run on any runtime that it finds. It still runs on the pin of the project.

Declare a requirement only for a need of the action itself:

  • An older release gives a wrong result, such as a pass without a test.
  • The error of the toolchain does not say that its pin is the cause, such as an unknown option that only a Rust nightly has.

That a tool runs on a toolchain is no such need. A package for Node.js can state the releases of Node.js that it supports. Do not copy them into a requirement, because the tool reports an unsupported release with its own error.

test-node has such a need. Node.js runs test files in TypeScript only from 22.18 and 23.6 on. An older release skips these files, finds no test, and passes. So the action returns a ToolchainRequirement from toolchains:

fn toolchains(&self) -> Vec<ToolchainRequirement> {
    // Node runs test files in TypeScript from 22.18 and 23.6 on. An older
    // release skips these files and reports no problem, so the run passes
    // without a test.
    vec![
        ToolchainRequirement::builder()
            .toolchain("node")
            .versions(VersionRange::new("^22.18 || >=23.6"))
            .build(),
    ]
}

The requirement holds the toolchain and a VersionRange. A range uses the syntax of a version requirement of Cargo, with two additions that Cargo does not have. A range joins alternatives with ||, and the range nightly-* accepts every dated Rust nightly. A requirement adds no pin, and the project still chooses the release.

You write no check of your own. Tool::resolve_toolchain reads the requirements of the action and takes the first pin that they all accept.

An Unmet Requirement

If the project pins no release that the requirement accepts, the lookup returns an error. The action stops with that error, and it does not skip. The error gives the requirement and the pin, and it says which pin to change.

Only the action with the requirement stops. Other actions and the custom commands of the harness still run. A group that holds the action runs its other members and fails. A run that skips because a tool has no build for the platform checks no toolchain.

doctor reports an unmet requirement of each mounted action, so that you find it before a run. It reports only the requirements that actions declare. An action that runs on a toolchain without a requirement, such as lint-rust on Rust, does not make doctor report a missing pin. That action stops with an error when it runs.

Test the Requirement

A test can read the requirement without a toolchain:

#[test]
fn toolchains_accept_only_a_node_that_runs_typescript() {
    let requirements = TestNode.toolchains();

    let ranges: Vec<&str> = requirements
        .iter()
        .map(|requirement| requirement.versions().get())
        .collect();

    assert_eq!(ranges, ["^22.18 || >=23.6"]);
}

A test that runs the action needs mise, because the lookup asks it about the pins of the project. A project that pins an older release shows that the action stops. Mise does not have to install the release, because the lookup compares the pin before it asks for the program:

#[tokio::test]
async fn run_on_a_node_that_skips_typescript_stops_with_an_error() {
    let project = Project::pinning_node("20.19.0");

    let outcome = project.run().await;

    assert!(
        matches!(
            &outcome,
            Outcome::Errored { source }
                if matches!(
                    source.downcast_ref(),
                    Some(ResolveToolchainError::UnmetRequirement { .. })
                )
        ),
        "expected the run to stop on the pin of Node, got {outcome:?}"
    );
}

Project is a helper of the test file. It writes the mise.toml of a temporary project and trusts it with mise trust, because mise ignores a configuration that nobody trusts.

Next Steps

Test an Action covers tests that run tools. Migrate From 0.1 shows how an action of 0.1 changes to declare its toolchains in this way.