Install and Verify Buildchain

Install and Verify Buildchain

Buildchain can be consumed as a standalone binary, an npm package, or a repository workflow surface. In every case, verify the release record before adopting a new version.

Standalone Binary

Buildchain v3.0.0 does not publish standalone platform archives. This section documents the verified legacy binary release contract; v3 consumers should use the npm package or repository workflow surface below.

Use the archive that matches the platform:

Linux example:

tag=v2.2.1
base="https://github.com/kungfu-systems/buildchain/releases/download/${tag}"
curl -LO "${base}/buildchain-x86_64-unknown-linux-gnu.tar.gz"
curl -LO "${base}/buildchain.release.json"
curl -LO "${base}/artifact-evidence.json"
npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz
./buildchain version

Windows example:

$tag = "v2.2.1"
$base = "https://github.com/kungfu-systems/buildchain/releases/download/$tag"
Invoke-WebRequest "$base/buildchain-x86_64-pc-windows-msvc.zip" -OutFile buildchain.zip
Invoke-WebRequest "$base/buildchain.release.json" -OutFile buildchain.release.json
Invoke-WebRequest "$base/artifact-evidence.json" -OutFile artifact-evidence.json
npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
Expand-Archive buildchain.zip -DestinationPath .
.\buildchain.exe version

The GitHub Release page does not publish loose top-level buildchain or buildchain.exe files. The executable is inside each platform archive.

npm Package

npm install -D @kungfu-tech/buildchain
npx buildchain version
npx buildchain doctor --json

The highest alpha minor publishes to the alpha npm dist-tag; older maintenance minor alphas use vX.Y-alpha so they cannot roll the global alpha channel back. Stable releases publish to latest. Both are created by the protected Buildchain promotion transaction.

Stable consumers should pin the exact Buildchain version they have validated, for example:

pnpm add -D @kungfu-tech/buildchain@3.0.0

If a repository dogfoods a just-published Buildchain version and pnpm’s release age policy blocks the install, use a temporary package/version-specific minimumReleaseAgeExclude entry instead of weakening the registry policy for all packages:

{
  "pnpm": {
    "minimumReleaseAgeExclude": [
      "@kungfu-tech/buildchain@3.0.0"
    ]
  }
}

Remove that entry after the package is old enough for the repository’s normal policy. Do not use a broad exclude such as @kungfu-tech/* for this case.

Repository Integration

npx @kungfu-tech/buildchain init --type package --package-manager pnpm
npx @kungfu-tech/buildchain validate --require-version-state
npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0

Use .buildchain/buildchain.toml to declare lifecycle commands. The commands may use Node package managers or non-Node tools such as pip, Conan, CMake, Make, or project scripts.

Verify a Release Passport

buildchain verify release-passport buildchain.release.json
buildchain explain release --passport buildchain.release.json --for agent --json

The verifier fails closed when the passport or its sibling evidence files are missing required fields or mismatching artifact digests.