--- name: circleci-deploy-rollback-check description: Check the deploy history for a CircleCI environment and component before any rollback, establishing which version is live, what it replaced, and whether the evidence supports rolling back, and requiring explicit approval before rollback_deploy_component runs. Use when the user asks whether to roll back a deploy, what version is live in an environment, what changed in the last deploy, or wants a safe rollback of a component. --- # Check a deploy before rolling it back A rollback is a production change made under pressure. The job is to establish, from the deploy record rather than memory, **what is live, what it replaced, and whether rolling back would actually restore something healthy**. Rolling back to a version that was also broken, or that is not the version the user thinks it is, makes an incident worse. Nothing changes until the user has seen the facts and given an explicit yes. ## 1. Pin down the environment and component Confirm with the user, in one line, which org, project, deploy environment and component are meant. A component name that exists in two environments is the most common way to roll back the wrong thing. Use `get_deploy_environment` and `list_deploy_environments` to confirm the environment exists and is the one named. Use `list_deploy_components` and `get_deploy_component` to confirm the component belongs to that environment. If the names are ambiguous, stop and ask. Do not guess between staging and production. ## 2. Establish what is live Use `list_deployments` for the component, newest first, and find the most recent deployment that is the live one. Record its version, the time it was deployed, and who or what triggered it. Then use `list_deploy_component_versions` to see the ordered version history. Answer these before going further: - **Which version is live right now?** Not "the latest deploy". A deploy can be queued, failed or superseded. - **Did the live deploy succeed?** A deploy that started and did not finish may have left a mixed state. - **What did it replace?** The immediately previous successful version is the usual rollback target. Note it explicitly. ## 3. Decide whether a rollback is the right fix Rolling back is one option among several, so work through the cheap checks first: - **Timing.** Did the problem start after the live deploy? If errors predate it, the deploy is probably not the cause, and a rollback will not help. - **Is the previous version also broken?** Check the run history of the previous version's deploy with `get_run` or `list_run_workflows`. If that build failed or was flaky, rolling back lands on a bad build. - **Is the problem data or config, not code?** A migration or config change shipped alongside the version may not roll back cleanly. Check the run that produced the live version for config or migration steps. - **Is there a faster fix?** A feature flag or a single job rerun may be the lower-risk move. Say which of these you checked and what each showed. ## 4. Check the rollback target's own health Before proposing the rollback, confirm the target version was healthy when it was live. Look at its deployment record and the run that built it with `get_run`, `list_jobs` and `get_job_logs` where it failed. A target that deployed cleanly and ran for a meaningful period is safe. A target that was rolled back from itself, or deployed and reverted quickly, is a red flag and should be reported. ## 5. Propose the rollback and wait Write up the proposal in the output format below, then ask for approval. Name the exact component, the current live version, and the exact target version. Make the target explicit so the user is not approving a vague "roll back". Use `rollback_deploy_component` only after the user's explicit yes in this conversation, for this exact component and target version. A yes to "look into it" is not a yes to roll back. If the user changes the target, or more than a few minutes pass, confirm again. ## 6. Verify after any rollback After `rollback_deploy_component` returns, re-read the deployment list with `list_deployments` and confirm the target version is now live. Report that confirmation. The rollback result alone does not show that the errors stopped; say that a human must check the service's own health signals, since this skill does not read them. ## Common patterns and traps - **Rolling back the wrong environment.** Staging and production often share component names. Always restate the environment in the approval request. - **"Latest" is not "live".** A newer deploy may be queued or failed. Work from the record of what actually went live. - **The previous version was also bad.** Two versions in a row failing usually means a shared cause, such as a dependency, a migration or a config change. A rollback then restores nothing. - **Migrations and config do not roll back with code.** If the live version changed schema or config, rolling the code back may break it. Flag this and do not assume the rollback is clean. - **Rolling back a version that never really ran.** A deployment that failed midway may not be the thing users saw. Confirm the target deployed successfully. - **Confusing rollback with rerun.** Rerunning a workflow rebuilds code; it does not change what is live. Keep these separate in the recommendation. - **Silent acceptance.** A user saying "just fix it" under pressure is not a yes to an unspecified rollback. Restate the exact target and ask again. ## Output ``` Environment / component: / Live version: , deployed