> ## Documentation Index
> Fetch the complete documentation index at: https://paper.brimble.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Deployments
> A deployment is a single attempt to roll out a new version of a project.
A **deployment** is a single attempt to roll out a new version of a project. Every push to your tracked branch creates one. So does every manual redeploy. This page covers the deployment lifecycle, the states a deployment moves through, and how rollbacks work.
## What triggers a deployment
A new deployment starts when:
* You push a commit to the branch tracked by the project.
* You click **Redeploy** in the dashboard.
* A pull request is opened against the tracked branch and the project has Preview environments enabled.
* An upstream service the project is linked to deploys, if you've configured chained deploys.
Each trigger creates a new deployment record with a unique ID, the commit SHA, the committer, and the message.
## Deployment lifecycle
A deployment moves through these states:
| State | Meaning |
| --------------- | --------------------------------------------------------------------------------------- |
| **Pending** | Queued. Waiting for a build slot to free up. |
| **In progress** | The build is running, or the build finished and the runtime is starting. |
| **Active** | The new version is live and serving traffic. |
| **Failed** | The build or the runtime startup errored. The previous active deployment keeps serving. |
| **Cancelled** | You stopped the deployment manually before it finished. |
| **Degraded** | The service is running but failing health checks. |
| **Inactive** | The project is disabled (for example, payment past due). |
Health checks promote a deployment from "in progress" to "active". A deployment that builds successfully but never passes a health check stays in `in progress` until it times out, then flips to `failed`.
## Phases inside a deployment
Each in-progress deployment streams logs through these phases:
1. **Clone.** Brimble fetches the commit from your Git provider.
2. **Detect.** The build pipeline inspects the repo to pick a builder (Railpack for backend; Brimble's frontend builder for static sites and SPAs).
3. **Install.** Dependencies are installed (`npm ci`, `pip install`, `bundle install`, etc.). The build cache is consulted here.
4. **Build.** Your build command runs. Compilation, bundling, asset generation, container image creation.
5. **Push.** The artifact is pushed to Brimble's internal registry.
6. **Deploy.** The container is scheduled in the target region.
7. **Health check.** Brimble probes the start command and, for web services, your `healthCheckPath` (defaults to `/`). When the check passes, traffic flips to the new deployment.
Logs for each phase stream into the dashboard in real time. You can also view them after the fact under **Deployment history**.
## Build queue
Deployments don't all run at once. Each plan grants a fixed number of **concurrent builds**:
* Free: builds queued, no concurrent build slot
* Hacker: 1
* Pro: 2
* Team: configurable (each extra concurrent build is metered)
If all your slots are busy, new deployments enter `pending` and start as soon as a slot opens. Cancel a queued deployment by clicking **Cancel** on the deployment in the dashboard.
## Rollbacks
Old deployments aren't deleted. Every previous build for a project sits in **Deployment history** with its commit, status, and timestamp. To roll back:
1. Open **Deployment history** for the project.
2. Find the deployment you want to restore.
3. Click **Redeploy this version**.
Brimble re-runs that deployment's image (no rebuild) and flips traffic to it. The rolled-back deployment becomes the new active one. Rollbacks are seconds, not minutes, there's no rebuild step.
## Cancelling a deployment
You can cancel a deployment at any time during the build or deploy phases. After it's active, "cancelling" doesn't apply, use **Redeploy this version** to roll back instead.
## Watching a deployment
Three places show deployment status:
* **Dashboard.** Status badge on the project, plus a live logs drawer.
* **Webhooks.** Brimble emits `deployment.started`, `deployment.success`, and `deployment.failed` events. See [Webhook events](../webhooks/events).
* **Deployment history** in the project, every previous build, with status, commit, and timing.
## Failed deployments
A failed deployment never receives traffic. The previously active deployment keeps serving. Common failure modes are documented in [Build failures](../troubleshooting/build-failures).
When a deployment fails, the dashboard shows the failed phase and the last 100 lines of logs. Read logs **bottom-up**, the first error is usually the real one; everything after it is fallout.
## Next steps
* [Environments](/environments/overview), Production, Preview, and how each gets its own deployment stream.
* [Builds](/projects/builds), how Brimble turns source code into an artifact.
* [Build failures](../troubleshooting/build-failures), common errors during a deployment.