Machine definitions

​

Overview

Most workflows spend their first few minutes installing the same dependencies. They set up a language runtime, install a package manager, pull system packages from apt, and download browsers or CLIs, and every job repeats it on a fresh VM before the real work starts. A machine definition describes the machine your jobs need, once: an Ubuntu base, x64 or ARM, the setup script your jobs keep repeating, and the environment variables they expect, with secrets kept secret. Blacksmith builds it into a machine image, so the setup is already there when a job starts. You don’t have to write the definition from scratch: Blacksmith drafts one from what your recent jobs installed and what your workflows set up, and you review it before you publish it. A few examples of what goes into one:

• A Next.js storefront whose end-to-end tests install Node 22, pnpm, ffmpeg and the fonts its screenshots need, then download Chromium and WebKit for Playwright on every run.
• A Rust service that pins a nightly toolchain and runs cargo install for sqlx-cli and cargo-nextest before it can build.
• A Python data pipeline that installs uv, a specific Python, and the Google Cloud SDK with the gke-gcloud-auth-plugin component.

​

How it speeds up CI jobs

Setup steps cost the same on every job, so they add up fastest where you run the most jobs: a test suite split across 20 shards pays for the same installs 20 times. With a machine definition, each job starts on an image that already has its toolchain and goes straight to checkout, build and test. Fewer downloads also mean fewer failures that have nothing to do with your code. Every package fetched from npm, PyPI, crates.io or an apt mirror is a chance for a rate limit or an outage to fail the job. When those packages are already in the image, a registry having a bad day doesn’t block your merge.

​

How it helps [code]smith

[code]smith works in a sandbox. Without your toolchain, it can write a change but often can’t run your tests, so it learns whether the change works the way you would: push, wait for CI, read the failure, and try again. With a machine definition, [code]smith’s sandbox starts from the same image your CI runs on. It runs your test suite, linters and build before it opens a pull request, fixes what breaks, and hands you a PR that already passes. When CI does fail, [code]smith can reproduce the failure in an environment that matches CI rather than guessing from the logs.