Show deployment progress

Deployment progress is the card in your product that tells a customer what their deployment is doing and who must act next. You show it when you launch the portal from your product with a Deploy button, or build it into your product with your own setup screen.

Every state comes from one call, GET /v1/deployments/{id}, read by your backend. Errors, blocked updates, and removal have their own pages:

• Errors and retries
• Updates and connection
• Follow removal

Waiting for setupCopy Anchor Link

The initial setup runs in the customer's account, with their admin's credentials, outside your product. Until it reports back, your page waits.

Show it when a deployment exists, status is pending or initial-setup, and lastHeartbeatAt is null.

• Console opened, nothing created. Opening the AWS console proves nothing. Keep this state until the deployment reports, even if the customer clicks Continue.
• Reload. Land on the same deployment. Reopen setup shows the same setup step instead of creating a second deployment.
• Check now. It only requests a check and returns requestedAt. Show "Check requested" until a newer resourceObservedAt arrives.
• Wrong person. The person who clicked often isn't the cloud admin. Send to an admin shares the setup link, not a screenshot of your page.
• Stack rolled back. On CloudFormation, setupMetadata.setupReservation.rolledBackAt means the stack failed before it reported back. See Come back to it.

{
  "id": "dep_0c29fq4a2yjb7kx3smwdgxlc",
  "status": "pending",
  "setupMethod": "cloudformation",
  "lastHeartbeatAt": null,
  "resourceObservedAt": null,
  "resources": []
}

Each action is one call with no body:

• Check now: POST /v1/deployments/{id}/check asks Alien to look for the deployment again, and returns 202 with requestedAt.
• Reopen setup: POST /v1/deployments/{id}/installation returns the same launch link, Terraform configuration or command, never a new deployment.

import { alien } from "./alien"

export const checkNow = (id: string) => alien.requestDeploymentCheck({ id })
export const reopenSetup = (id: string) => alien.resumeDeploymentInstallation({ id })

Setting upCopy Anchor Link

While Alien creates the live resources, show them grouped by category, as the deployment portal and the Alien dashboard do. The example at the top of this page shows this state.

Show it when status is provisioning, waiting-for-machines, or waiting-for-secrets.

• Closed categories. Each category shows one status. Open one on its own only when it holds a failed resource.
• No percentages. Resources finish in parallel and take different times. Don't show a progress bar or an ETA.
• Long setups. A first deployment usually takes 10 to 20 minutes. Say so once, and let the customer leave the page.
• progress is for people. Show it as is; never branch on it. It's null when there's nothing to say.
• Missing secrets. waiting-for-secrets needs the customer. Name the secret from runtimeMetadata.deployerSecrets, where status is missing or invalid, and link to Inputs and secrets.

{
  "status": "provisioning",
  "resourceObservedAt": "2026-01-15T09:04:48Z",
  "resources": [
    {
      "id": "compute",
      "displayName": "Compute cluster",
      "type": "compute-cluster",
      "status": "provisioning",
      "progress": "Waiting for machines to join the cluster.",
      "error": null,
      "retryAttempt": 0
    }
  ]
}

resources lists every resource in the deployment, including the network, identities, and cloud APIs Alien adds for the platform:

resourceObservedAt says when Alien last read the resources; show it as "Last update".

Set the names in alien.ts, so the resources read like your product:

const api = new alien.Container("api")
  .displayName("API server")
  .description("Serves the document processing API.")
  // ...
  .build()

Resources Alien adds have built-in names, such as Network and Management identity. See Supporting resources.

CategoriesCopy Anchor Link

Pick each resource's category from its type, and show the categories in this order. Leave out empty ones.

Each category row shows its name, a count, and one status, worst first:

• N failed if any resource failed.
• Setting up if any is pending, provisioning or updating.
• Deleting if any is deleting.
• Running otherwise.

Inside a category, list failed resources first, then in-progress ones, then the rest in the order resources returns them. Each resource gets one line, with progress or the error message on a second line.

ReadyCopy Anchor Link

running with currentReleaseId equal to desiredReleaseId means Alien finished. It doesn't mean your product can reach the service yet.

Show it when status is running, currentReleaseId equals desiredReleaseId, and your own connection test hasn't passed yet.

• Not yet active. Your product turns the feature on after its own test passes. See Verify and activate.
• Closed categories. Every category shows Running and starts closed.
• Running an older release. When currentReleaseId differs from desiredReleaseId, an update is pending. See Updates and connection.

{
  "status": "running",
  "currentReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",
  "desiredReleaseId": "rel_WbhQgksrawSKIpEN0NAssHX9",
  "lastHeartbeatAt": "2026-01-15T09:21:03Z",
  "updateState": { "active": null, "next": null, "latest": null }
}

Read the deploymentCopy Anchor Link

Poll from your backend, never from the browser: the Alien API key stays on your server. Store what you read in your own database and serve your page from it. The clients are set up in Set up a client.

import { alien } from "./alien"

export async function readDeployment(deploymentId: string) {
  const d = await alien.deployments.get({ id: deploymentId })
  return {
    status: d.status,
    resources: d.resources, // id, displayName, status, progress, error, retryAttempt
    update: d.updateState.active, // a blocked or running update, or null
    error: d.error,
    lastHeartbeatAt: d.lastHeartbeatAt,
  }
}

• Polling. Every 10 to 30 seconds while the customer watches, and every few minutes from a background job otherwise.
• API errors. Back off: double the delay up to two minutes, keep showing the last state you read, and reset after a good read.
• Stop when the state settles: ready, failed, waiting on the customer, or removed.
• Webhooks. To hear about changes without polling, add a webhook endpoint. Alien sends events such as deployment.running or deployment.failed, and your server reads the deployment then.

To find the deployment first, see When they come back.

Status mapCopy Anchor Link

Your page needs a few states, not Alien's full lifecycle. Map each status to one:

Test itCopy Anchor Link

• Unit-test your mapping with the responses on this page and its sibling pages. Assert the headline, categories, and actions for each.
• Deploy for real into a test account. Watch every state, then reload during initial setup and confirm the page shows the same deployment.
• Missing secret. Leave a deployer secret unset, and check your page names it.

NextCopy Anchor Link

• Errors and retries: what to show when a resource fails
• Verify and activate: turn the feature on
• Updates and connection: blocked updates and stale heartbeats
• Debug a deployment: when a state needs your team