Crossplane "crossplane: command not found" in CI

By Kaveh Alemi·Latchkey

The shell could not find a crossplane executable on PATH. The Crossplane CLI is a separate binary from kubectl, and CI runners do not ship it, so a step that calls crossplane fails until you install it.

What this error means

A step running crossplane beta validate or crossplane xpkg build exits 127 with "crossplane: command not found", even though kubectl works.

/home/runner/work/_temp/script.sh: line 1: crossplane: command not found
Error: Process completed with exit code 127.

Common causes

The CLI was never installed on the runner

Runner images include kubectl but not the Crossplane CLI, so the first crossplane invocation fails.

Installed to a directory not on PATH

The install script placed the binary in a local directory that the later step never added to PATH.

How to fix it

Install the Crossplane CLI in a setup step

1. Run the official install script, which downloads the crossplane binary.
2. Move it onto PATH (for example /usr/local/bin).
3. Verify with crossplane --version before using it.

curl -sL https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh | sh
sudo mv crossplane /usr/local/bin/
crossplane --version

Pin a specific CLI version

Pass a version to the install script so CI does not silently jump to a new CLI that changes flags or behavior.

curl -sL https://raw.githubusercontent.com/crossplane/crossplane/main/install.sh | CHANNEL=stable VERSION=v1.16.0 sh
sudo mv crossplane /usr/local/bin/

How to prevent it

• Install the Crossplane CLI in an early, cached setup step.
• Pin the CLI version so flags and output stay stable across runs.
• Verify crossplane --version before any command that depends on it.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation