Deployments
Last updated on November 19, 2026
A deployment is the built artifact of a Procedure at a specific commit. It carries the executable, the resolved runtime, the configuration, and every input the CLI needs to run the procedure on a Station. The artifact is immutable, so a station running a given deployment always runs the same code.
You can create a deployment in three ways: through a Git push, a manual trigger from the dashboard, or the CLI. The REST API lists them and reads their details.
Deployment methods
TofuPilot exposes the same deployment pipeline through several entry points so you can pick the one that fits your workflow.
Git push
When you push to a connected Git repository, every push to a branch that is not excluded creates a deployment for its latest commit. When auto-push is on, commits on the production branch are built and rolled out to every linked station, and commits on other branches are built as preview deployments that stay off your stations. See Environments for the exact conditions.
The following providers are supported out of the box:
- GitHub: Free, Team, and Enterprise Cloud.
- GitLab: Free, Premium, Ultimate, and Self-Managed.
- Bitbucket: Data Center / Server. Bitbucket Cloud is not supported yet.
Manual trigger
From the procedure's Deployments page, click + to open New manual deployment, then pick a branch and a commit. The build worker compiles that exact revision and produces a deployment record. A manual deployment builds only: push it to your stations once it is ready.
CLI
The CLI creates a deployment directly from your local working tree, with or without a connected repo. It uploads the working copy as an artifact and produces a deployment record you can pin to any station.
REST API
The REST API reads deployments so you can follow them from your own automation:
GET /v2/deploymentslists deployments, filtered by procedure and paginated.GET /v2/deployments/{id}returns one deployment with its build logs and the stations it was pushed to.
Creating a deployment and pushing it to stations happen through Git, the dashboard, or the CLI.
Lifecycle
A deployment moves through a small set of statuses from queue to finished build. The table below lists what each status means.
| Status | Meaning |
|---|---|
pending | Queued for build and waiting for a worker. |
building | The build worker is producing the artifact and logs stream live in the dashboard. |
ready | Built and signed. The deployment is eligible to run on a station. |
failed | The build failed and the deployment cannot be pinned. |
A build that fails because of the build service itself (a worker restart, a network error while cloning or uploading) is retried automatically, up to two more times. A build that fails because of the procedure (its build script exits with an error, or runs past its time limit) is not retried. Fix the procedure and push again, or click Redeploy in the deployment's row menu. A redeploy keeps the deployment's environment. Redeploying the latest production deployment, when it failed on its way to your stations, sends the new build to them once it is ready. Redeploying any other deployment only builds it: to put your stations back on an older build, use Instant Rollback.
Skipped pushes
A Git push that auto-push records without building it is listed as Skipped. Hover the status to see why:
| Reason | What to do |
|---|---|
| Production is rolled back | Push a deployment to all stations to end the rollback. Pushes are not deployed while it lasts. |
| Auto-deploy is off | Turn auto-push on, or deploy the commit yourself. |
| Neither the person who pushed nor the commit author is a member with deploy permissions | Push as a member with the Owner, Admin, or Developer role, with their Git account linked. |
| No station is linked | Link a station to the procedure, then push again. |
Pushing the same commit again after fixing the cause builds it. A push to an excluded branch is not recorded at all.
Environment
Every deployment is created in one of three environments, and the environment is fixed at creation. The label does not change when the production branch moves, even if the same commit is later promoted. See Environments for the full lifecycle.
| Environment | Created by |
|---|---|
production | A push to the production branch, or a manual promote of a preview deployment. |
preview | A push to any non-production branch, or a manual trigger from a commit. |
development | A local CLI session. The artifact is never uploaded as a long-lived record. |
Trigger
Every deployment records how it was created so you can audit the source of a build.
| Trigger | Created by |
|---|---|
auto | Fan-out from a push webhook on the linked Git repo. |
manual | A manual deployment or a Redeploy from the dashboard. |
cli | tofupilot deploy from a working tree. |
Fields
Each deployment exposes the following fields through the API and dashboard.
| Prop | Type | Default |
|---|---|---|
id? | string | – |
procedure? | object | – |
commit? | object | – |
environment? | enum | – |
trigger? | enum | – |
status? | enum | – |
skipped? | boolean | – |
platform? | string | null | – |
language? | string | null | – |
runtime_version? | string | null | – |
started_at? | datetime | null | – |
ended_at? | datetime | null | – |
artifact_size_bytes? | integer | null | – |
Fan-out to stations
When auto-push is on, production deployments roll out automatically. Stations receive a production deployment once its build is ready, so a build that fails never replaces the code they run. When you push twice in a row, stations end on the newer deployment, whichever build finishes first. Every station bound to the production branch picks up the new deployment between Runs, and the swap happens during the idle window so in-flight runs finish against the version they started with.
Each station tracks one active deployment per procedure, and a newer deployment moves the active pointer forward. Removing the deployment from the station clears the pointer, so the station cannot run the procedure until another deployment is pushed. Unlinking the procedure also clears it, and the station gets a deployment again only once the procedure is linked back.
If you prefer to stage the rollout instead of fanning out at once, see Rolling rollout.
Auto-push configuration
You configure auto-push from the procedure's Settings > Repository page, where you can:
- Toggle Auto-push on or off.
- Pick the production branch (default
main). - Exclude branches you do not want to build.
Disable auto-push when you want to decide yourself what gets built and rolled out. Pushes are still recorded, but nothing is built. Deploy a commit from the dashboard to build it, then push it to your stations.
Managing deployments
The Deployments tab lists every build with its status, commit, build duration, artifact size, and active stations. From each row, you can take the following actions:
- Push to All Stations sends the build to every linked station. From the deployment's page, you can also push it to one station.
- Instant Rollback moves every station back to a previous build, as described in Instant rollback.
- Redeploy builds the same commit again as a new deployment.
- Open the row to see the build logs, environment, runtime version, and artifact contents.
- Delete removes a build you no longer need, as described in Deleting a deployment.
Inspecting a deployment
Open any deployment to see the full context of the build:
- Commit metadata (SHA, message, author, branch).
- Build logs with timestamps.
- Resolved runtime version and platform. Stations provision the matching minor line — see Python version.
- Artifact contents (procedure YAML, Python packages, supporting files).
- Stations currently running this deployment.
- Runs produced by this deployment.
Removing a deployment from a station
Removing a deployment takes it off a station without unlinking the procedure, so the station can still upload runs for that procedure. Click Remove next to the station on the deployment's page, or Remove deployment in the procedure's menu on the station's page.
A station running the TofuPilot CLI deletes its local copy of the code at its next pull, and cannot run the procedure until another deployment is pushed. Removing the deployment asks the station to pull right away. A station that is in the middle of a test, or offline, keeps the code until its next pull while idle or until it restarts.
Deleting a deployment
Delete a deployment from its page, or from the menu of its row in the Deployments tab. Deletion is permanent and also removes its build logs and push history.
A deployment cannot be deleted while:
- It is active on a station. Remove the deployment from the station first.
- Its build is queued or running. Cancel the build first.
- Runs were produced by it. Runs keep the deployment that produced them.
- It is the target of an instant rollback. Click Resume auto-push in the banner of the Deployments tab, or push another deployment to all stations, before deleting it.
A station that still has the code of a deleted deployment can keep running it until its next pull. Those runs are uploaded without a link to the deleted deployment.
How is this guide?