# Release train

> Your environments down a rail, each with the version it runs: promote one and a copy rides down to the next station, waits while it deploys, then docks.

Deploy pages usually list environments as rows of status badges, and a promotion is a spinner that turns into a new version number, so you can’t see what moved where or what is still running while it deploys. Release train lays your environments down a rail, each with the version it runs in a chip at the end of its row. Between two stations whose versions differ sits a small switch on the rail. Press it and a copy of the version peels off the chip above and rides down to the line between the two stations, where it waits with a ring that fills with your progress while the old version still runs below. When the deploy is live it docks: the new chip slides into the slot and pushes the old one out to the side. If it fails, the chip stops on the line, its ring turns red with a small shake and the reason folds open under the station with Retry. A rollback brings the version that was pushed out back in from the side. The stations are your records and every action is one async function.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/release-train.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `status-button`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/release-train
- Registry item (source): https://hairlineui.com/r/release-train.json

## Usage

```tsx
import { ReleaseTrain } from "@/components/release-train";

<ReleaseTrain
  stages={[
    { key: "staging", label: "Staging", version: "v1.42.0" },
    { key: "production", label: "Production", version: "v1.41.2" },
  ]}
/>
```

## Promote through your deploy API

Keep the stations in state from your API; a promote starts a deploy and you poll it until it’s live or failed.

```tsx
"use client";
import * as React from "react";
import { ReleaseTrain, type ReleaseStage } from "@/components/release-train";

export function Deploys({ initial }: { initial: ReleaseStage[] }) {
  const [stages, setStages] = React.useState(initial);

  React.useEffect(() => {
    // Your deploy API returns each environment's version, status, incoming, progress and error.
    const id = setInterval(async () => setStages(await fetch("/api/environments").then((r) => r.json())), 2000);
    return () => clearInterval(id);
  }, []);

  async function post(path: string, body: object) {
    const res = await fetch(path, { method: "POST", body: JSON.stringify(body) });
    if (!res.ok) throw new Error(await res.text());
    setStages(await res.json());
  }

  return (
    <ReleaseTrain
      title="Releases"
      caption="web · main"
      stages={stages}
      onPromote={(from, to) => post("/api/promote", { from, to })}
      onRetry={(env) => post("/api/retry", { env })}
      onRollback={(env) => post("/api/rollback", { env })}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `stages` | `ReleaseStage[]` | – | In order down the rail: { key, label, detail?, version?, previous?, status?: "live" \| "deploying" \| "failed", incoming?, progress? (0–1), error? }. |
| `title / caption` | `string` | `"Releases"` | The heading and a short line beside it, e.g. the repo and branch. |
| `onPromote` | `(from, to) => Promise<unknown> \| void` | – | Shows the switch between two stations whose versions differ. Set the next station deploying when it starts; throw to refuse. |
| `onRetry` | `(key) => Promise<unknown> \| void` | – | Shows Retry under a failed deploy. |
| `onRollback` | `(key) => Promise<unknown> \| void` | – | Shows “Roll back to …” on a station with a previous version. |

## States

- **stations**: Each environment is a station on a hairline rail: a dot in its chart colour, its name and URL, and the version it runs in a grey chip at the end of the row.
- **promote**: Where a station’s version differs from the next one’s, a 20px switch with a down arrow sits on the rail between them. Pressed, it spins until the next station starts deploying; if your function throws it shakes and stays.
- **deploying**: A copy of the chip glides from the station above to the line between the two (620ms) and waits there with a ring that fills to your progress (600ms ease), or spins while progress is unknown. The station’s dot turns hollow.
- **live**: The waiting chip slides down into the slot (460ms) and the old one slides out to the side through a blur (380ms).
- **failed**: The ring turns red with a ×, the chip shakes (380ms), the dot turns red and the reason folds open under the station (420ms) with Retry.
- **rollback**: “Roll back to v1.41.1” shows under a station with a previous version. Pressed it reads Rolling back; when the version changes the old chip comes back in from the side and the current one leaves.
- **reduced motion**: Chips change in place; folds and rings change without easing.

## What it handles

A deploy page of status badges shows a spinner and then a new number, so you can’t see what moved where, or what is still running while it deploys.

- **What runs where**: Every environment shows the version it runs, in one column you can read down.
- **Promote on the rail**: A switch between two stations appears only where their versions differ.
- **The old one keeps running**: The new version waits on the line with its progress until it’s live.
- **Failure in place**: The chip stops, turns red and the reason folds open under the station with Retry.
- **Rollback you can see**: The version that was pushed out comes back in from the side.
- **Your data, your calls**: Plain records in; promote, retry and rollback are async functions that can refuse.

## Replaces

a deploy pipeline, environment status badges, a promote button, a rollback menu, a deployment progress bar, a CI stepper

## Where it fits

- **Deploy and CI dashboards**: Preview, staging and production, what each runs, and promoting between them.
- **Release managers**: Moving a mobile or desktop build from beta to production channels.
- **Feature and model rollouts**: A model or config version moving from shadow to canary to everyone.
- **Internal admin tools**: Where each service’s version stands, with a rollback on the station that needs it.

## Notes

- The list is an ordered list; each station is named with what it runs or what is deploying to it (“Production: deploying v1.42.0”). The switch is a button named “Promote v1.43.0 to Staging”, shown only where it can act; Retry and Roll back are Status buttons.
- Chips glide by transform from where their version was a moment before (measured from layout, then one Web Animation each); a chip that leaves is kept just long enough for its exit.
- Every action is one async function; the switch and buttons show pending until your stations change, and shake if the function throws.
- Station colours come from your chart colours in turn. Installs Status button.
- With reduced motion chips change in place.

License: MIT (https://hairlineui.com/license#components)
