back
loading skill details...
Guide safe blue-green deployments with persistent repo config, environment state, health checks, explicit switch confirmation, and rollback discipline.
---
name: bluegreenpilot
description: "Guide safe blue-green deployments with persistent repo config, environment state, health checks, explicit switch confirmation, and rollback discipline."
version: 2026.6.4
homepage: https://github.com/ThiagoCAltoe/bluegreenpilot
metadata: {"openclaw":{}}
---
# BlueGreenPilot
Use this skill when the user wants to configure, plan, verify, deploy, promote,
switch traffic, or roll back a blue-green deployment flow.
BlueGreenPilot is a deployment safety protocol. It must help the user operate
their real environment without relying on chat memory or guessing.
## Hard Rules
- Never switch production traffic without explicit final confirmation.
- Never deploy to the active production slot unless the user explicitly says
they are not using blue-green for that environment.
- Never store secrets in `.bluegreenpilot/config.yaml`.
- Never assume the active slot. Read state, query the environment, or ask.
- Never assume a project is greenfield. If `.bluegreenpilot` is missing and the
user mentions production, first ask whether production already exists.
- Never treat an environment as a blue-green slot. `dev`, `homolog`, `staging`,
and `prod` are environments; `blue` and `green` are slots inside one
environment.
- Never say `homolog` is `green` or `prod` is `blue` unless config explicitly
models that nonstandard topology and the user confirms the risk.
- If a project has `homolog` and `prod`, treat it as a candidate for mapping,
not as proof that blue-green is already implemented.
- Stop if the state backend is unknown or unreadable.
- Stop if brownfield adoption says the inactive production slot is not
provisioned.
- Stop if rollback is unknown for production.
- Stop if database changes are involved and snapshot/migration policy is unknown.
- Prefer read-only discovery before any write/deploy action.
- Treat `homolog` as production-like for safety checks and data policy, but not
as a production traffic slot unless config explicitly says so.
- Always produce a plan before running deployment commands.
- Record what changed after every switch or rollback.
## Environment vs Slot Model
Keep environments and slots separate.
- Environments are deployment stages such as `dev`, `homolog`, `staging`, and
`prod`.
- Slots are parallel runtime targets inside one environment, such as `blue` and
`green`.
Correct model:
```txt
homolog
single-slot, or homolog-blue/homolog-green if explicitly configured
prod
blue: active production slot
green: inactive production candidate slot
```
Incorrect model:
```txt
homolog = green
prod = blue
```
If the user says an app has homolog and prod, say it is a good candidate for
BlueGreenPilot mapping. Do not claim blue-green exists yet. First discover
whether production can run two equivalent slots and switch traffic between them.
## Files
Use these files in the target application repository:
```txt
.bluegreenpilot/config.yaml
.bluegreenpilot/state.dev.yaml
.bluegreenpilot/state.homolog.yaml
.bluegreenpilot/state.prod.yaml
.bluegreenpilot/history/
```
`config.yaml` is versioned and contains topology/workflow only. Environment
state may be versioned for simple projects, but production state is usually
stored in CI artifacts, the server, object storage, or another trusted backend.
Secrets belong in `.env`, CI secrets, server env vars, Vault, Doppler, 1Password,
or equivalent secret storage.
The `state.backend` config field tells the agent where state persists across
developer machines, homolog, CI, and production. If the backend is not readable,
stop and ask how to retrieve state before planning a deploy.
## Standard Workflow
1. Identify the requested operation: init, status, plan, deploy, verify, switch,
promote, rollback, or audit.
2. Read `.bluegreenpilot/config.yaml`. If missing, run init workflow.
3. Determine target environment: dev, homolog, prod, or custom.
4. Read state for that environment. If missing or stale, ask how to retrieve or
initialize it.
5. Confirm active and inactive slots for blue-green environments.
6. Check deploy mode: no-docker, docker, mixed, CI, script, manual.
7. Check database policy: snapshot, mock, empty, manual, or none.
8. Generate a concise plan with commands, checks, switch method, rollback path,
and unknowns.
9. Ask before executing state-changing actions.
10. After execution, record result, commit/release id, active slot, checks, and
rollback metadata.
## Init Workflow
Ask only for missing facts:
- App name.
- Whether production already exists today.
- Branch model: single branch, dev/homolog/prod, or custom.
- Environments: dev, homolog, prod, custom.
- For each environment: deploy mode, blue-green or single-slot, URLs.
- Docker usage: none, all environments, homolog only, prod only, or mixed.
- Switch method: manual, script, nginx, Cloudflare, load balancer, CI, other.
- Rollback method.
- Healthcheck path and smoke commands.
- Database type and whether deploys include migrations.
- Homolog data mode: production snapshot, mock data, empty database, manual.
- Where state should be stored.
Create `.bluegreenpilot/config.yaml` and example state files. Do not ask for
secrets. If a command needs a secret, reference an env var name instead.
## Existing Production / Brownfield Adoption
If the app is already live, do not start by proposing a blue-green switch.
Adopt current production first:
1. Ask for the current production URL, deploy mode, current release/source, and
whether the current live service should be labeled `blue` or `green`.
2. Treat the current live service as the stable active slot.
3. Mark the opposite production slot as `not-provisioned` until the user creates
an equivalent secondary production slot. A homolog/staging environment does
not count as the inactive production slot unless the user deliberately
defines that topology and accepts the risk.
4. Record `adoption.mode: brownfield` and `inactive_slot_status:
not-provisioned`.
5. Block deploy/switch plans until the inactive slot is provisioned and verified.
If the CLI is available, use:
```bash
bluegreenpilot --project /path/to/app adopt-prod \
--app <name> \
--public-url <current-prod-url> \
--deploy-mode <docker|script|manual|ci|mixed|no-docker> \
--active-slot <blue|green> \
--source <current-release-or-commit> \
--state-backend <repo|server-file|ci-artifact|object-storage|manual>
```
## Deploy Plan Shape
Always show:
```txt
Target: <environment>
Current active slot: <slot or unknown>
Deploy target: <inactive slot>
Source: <branch/tag/commit>
Database policy: <snapshot/mock/empty/manual/none>
Pre-flight checks:
- ...
Deploy steps:
- ...
Verification:
- ...
Switch:
- method
- requires final confirmation: yes/no
Rollback:
- ...
Unknowns / blockers:
- ...
```
## Production Switch Gate
Before switching production, ask a direct confirmation that includes:
- target environment;
- current active slot;
- proposed new active slot;
- release/commit;
- healthcheck result;
- rollback command or procedure.
Do not proceed from vague approval. The user must clearly approve the switch.
## Rollback Workflow
For rollback:
1. Read current state.
2. Identify last known stable slot/release.
3. Check whether rollback affects database state.
4. Generate rollback plan.
5. Ask for confirmation.
6. Switch back or run rollback command.
7. Verify public URL.
8. Record rollback reason and result.
## Variant References
Read only the relevant reference:
- Docker and mixed Docker deployments: `references/docker.md`
- No-Docker/manual/script deployments: `references/no-docker.md`
- Database snapshot/mock/empty policy: `references/database.md`
- Config/state model and examples: `references/configuration.md`
## Helper Script
If available, use:
```bash
bluegreenpilot init
bluegreenpilot --project /path/to/app validate --env prod
bluegreenpilot --project /path/to/app status prod
bluegreenpilot --project /path/to/app plan prod --source <branch-or-commit>
```
If only the skill bundle is installed, use the bundled helper:
```bash
python {baseDir}/scripts/bluegreenpilot.py init
python {baseDir}/scripts/bluegreenpilot.py adopt-prod --app <name> --public-url <current-prod-url>
python {baseDir}/scripts/bluegreenpilot.py status --env prod
python {baseDir}/scripts/bluegreenpilot.py plan --env prod
```
The helper is conservative. It creates templates and reports missing facts; it
does not switch traffic or run destructive deployment commands.
don't have the plugin yet? install it then click "run inline in claude" again.
bluegreenpilot guides safe blue-green deployments for applications that need zero-downtime releases. use this skill when the user wants to initialize deployment topology, check current state, plan a release, execute a deployment, verify health, switch traffic between slots, or roll back to a prior slot. the skill enforces a hard distinction between environments (dev, homolog, prod, custom) and slots (blue, green) within those environments. it reads persistent config and state from the repo, discovers the real active slot, generates explicit switch plans with rollback paths, and blocks traffic switches without direct user confirmation. deploy only when you have read state, identified the inactive slot, checked health, and received clear approval.
Required files in target repo:
.bluegreenpilot/config.yaml (topology, workflow, deploy modes, healthcheck paths).bluegreenpilot/state.<env>.yaml (current active slot, release id, healthcheck status per environment).bluegreenpilot/history/ directory (append-only log of switches and rollbacks)External connections (if using CLI helper):
state.backend in config).bluegreenpilot/config.yaml)Environment variables (if deploy commands need them):
BLUEGREENPILOT_STATE_BACKEND (optional override for state backend location)Context from user:
Identify operation type. ask the user or infer from context: init, status, plan, deploy, verify, switch, promote, rollback, or audit. if ambiguous, ask.
Read config. check .bluegreenpilot/config.yaml in the target repo. if missing, run init workflow (see decision points). if present, parse app name, environments, slots per environment, deploy modes, switch methods, healthcheck path, database policy, and state backend.
Determine target environment. confirm which environment the user wants to work on (dev, homolog, prod, or custom). do not assume. if user mentions "production" or "live", clarify whether they mean the prod environment or homolog treated as production-like.
Read state for target environment. fetch .bluegreenpilot/state.<env>.yaml or query the state backend (ci artifact, object storage, server file, manual). if missing or unreadable, stop and ask how to retrieve or initialize state before proceeding.
Input: environment name, state backend location. Output: parsed state object containing active_slot, inactive_slot, current_release, last_switch_time, healthcheck_status, rollback_metadata.
Confirm active and inactive slots. extract from state the current active slot (blue or green) and inactive candidate slot. if state is missing or contradictory, query the real deployment (e.g., ask "which url is live right now?" or check load balancer config). record the discovery in state before proceeding.
Input: state, environment url(s). Output: confirmed active_slot, inactive_slot.
Validate state freshness and consistency. check the timestamp of the last state update. if older than 1 hour for prod or 4 hours for homolog, and the user has not explicitly said "use cached state", ask whether to refresh. check that active_slot matches the real running release (via healthcheck, deployment log, or manual confirmation).
Input: state timestamp, current time, user intent. Output: go/no-go for plan, or request to refresh state.
Determine deploy mode. read deploy_mode from config or ask: docker, script, ci, manual, no-docker, or mixed. this determines which deploy commands or steps to suggest later.
Input: config, environment. Output: deploy_mode string.
Determine database policy. read database.policy from config or ask: snapshot, mock, empty, manual, or none. if the user is deploying code that includes migrations or schema changes, and policy is unknown, stop and ask before proceeding.
Input: config, deploy source (diff/commits), environment. Output: database_policy string.
Check state backend readability. if state.backend is set to ci-artifact, object-storage, or server-file, verify that the skill can read and write state (test auth, permissions, network). if unreadable, stop and ask how to configure credentials or access.
Input: state backend config, credentials (from env vars or user). Output: backend_ok (true/false) or error message.
Generate deploy plan. assemble a plan including:
Input: config, state, source, target environment, deploy mode, database policy. Output: plan object (structured text or YAML).
Ask before executing state-changing actions. before running any deploy, switch, or rollback command, show the plan to the user and ask for explicit approval. for production, ask a direct confirmation gate (step 15 below). do not execute on vague assent.
Input: plan, environment risk level. Output: user approval (yes/no) or request to modify plan.
Execute deploy (if approved). run pre-flight checks, deploy steps, and verification in order. log each step (command, exit code, output snippet) as you go.
Input: plan, approval, state. Output: deployed_slot, release_id, healthcheck_result, updated state.
Verify health of newly deployed slot. call the healthcheck endpoint on the inactive (now deployed) slot. poll up to 3 times with 10-second intervals if the first call times out or returns 5xx. if healthcheck fails after 3 retries, mark slot as unhealthy and block traffic switch.
Input: healthcheck_path from config, deployed slot url, timeout (default 10s). Output: healthcheck_status (ok, timeout, fail) and result details.
Generate switch plan (traffic cutover). if deploy and healthcheck both pass, generate a switch plan that shows:
Input: config, state, healthcheck_result, deploy_mode. Output: switch_plan object.
Production switch gate (prod environment only). before switching production traffic, ask direct confirmation including all of:
do not proceed unless user explicitly approves all items. if user says "looks good" or "go ahead" without addressing rollback or healthcheck, ask them to confirm rollback explicitly.
Input: switch_plan, healthcheck_result, state. Output: explicit approval (yes/no), or request to clarify rollback.
Execute switch (if approved). run the switch method (script, api, manual step, ci trigger, etc.). record the time, new active slot, and old active slot in state and history.
Input: switch_plan, approval. Output: switch_result (ok/fail), new active slot, switch timestamp.
Post-switch verification. after traffic switch, call the healthcheck endpoint on the now-active slot. verify that the public url returns 200 and expected content. check logs for errors in the first 30 seconds.
Input: public url, healthcheck_path, active slot. Output: post_switch_healthcheck_result (ok/fail).
Record switch outcome. append to .bluegreenpilot/history/<timestamp>.<env>.yaml a record including:
update .bluegreenpilot/state.<env>.yaml with new active_slot, current_release, last_switch_time, and healthcheck_status.
Input: switch_result, healthcheck_result, state, user context. Output: updated state file, new history entry.
Rollback workflow (if rollback requested or switch failed). execute only if user asks or health check post-switch fails:
Input: current state, rollback_reason, history. Output: rolled_back_slot, verified healthcheck, updated state and history.
Status / audit operations (read-only). if user asks for current status or audit log:
Input: target environment. Output: status report or audit log.
If .bluegreenpilot/config.yaml is missing:
run init workflow. ask the user for app name, environments in use, deploy modes, switch method, rollback method, healthcheck path, database policy, and state backend location. create config and state template files. do not create anything until user confirms the topology.
If the app is already live in production (brownfield adoption):
do not propose a blue-green switch as the first step. instead, adopt the current production as the active slot (label it blue or green). mark the opposite production slot as not-provisioned until the user provisions an equivalent secondary production slot. block any deploy/switch plan until the inactive slot is provisioned and verified. if the only other environment is homolog, do not treat homolog as the production blue-green slot unless the user explicitly says they want that topology and accepts the risk.
If state is missing or unreadable for the target environment: stop and ask how to retrieve state (e.g., "is state stored in s3? what bucket?", "is state in a ci artifact?", "should i ask the deployment server?"). do not guess the state backend or assume defaults.
If the state backend is unknown or unreadable (auth failure, network timeout, missing file): stop. do not proceed with a deploy or switch plan. ask the user to provide credentials, fix network access, or retrieve the state file manually.
If the inactive production slot is not provisioned (brownfield adoption): stop. do not allow a deploy or switch until the user confirms the secondary production slot is ready. the deploy target must be an actual runtime environment, not a development or staging slot.
If database migrations or schema changes are in the deploy source, and database policy is unknown or set to manual: stop and ask the user: will the migration run before or after the traffic switch? should we snapshot prod before? do we need to run a dry-run migration on the inactive slot first? do not assume the database can be updated without coordination.
If the rollback method for production is unknown: stop. before any production switch, confirm with the user how they will roll back (e.g., "we will switch traffic back to blue", "we will redeploy the prior commit to green", "we have a database snapshot to restore"). if the answer is "manual", ask them to describe the manual steps. do not allow a production switch without a documented rollback path.
If the healthcheck returns timeout or 5xx after 3 retries: mark the newly deployed slot as unhealthy. block the traffic switch. report the healthcheck failure to the user. ask whether to investigate the deployed slot logs, roll back the deploy, or retry the healthcheck.
If the public url healthcheck fails after a traffic switch: this indicates a real production incident. immediately switch traffic back to the prior active slot (auto-rollback if user permits, or ask for manual switch). record the incident in history. ask the user to investigate the newly switched slot while traffic is restored to the prior version.
If the user says "deploy to prod" and production already has two slots provisioned and one is active: assume blue-green and deploy to the inactive slot, then require an explicit switch gate. do not deploy directly to the active slot.
If the user says "i want to deploy to prod" but does not specify which slot or branch: ask them to provide the source (branch, tag, or commit) and confirm they want to deploy to the inactive slot only, not switch traffic yet.
If the user is deploying to homolog, which is production-like (homolog data = prod snapshot): treat it as a safety-critical environment. apply the same pre-flight checks as prod (verify state, validate healthcheck path, confirm rollback method). do not skip steps just because it is not prod. if homolog uses prod data snapshot, treat it with prod-level discipline.
If the user asks for a status check and state is stale (>1 hour for prod): show the cached state, but note that it is stale. ask whether they want to refresh state before planning a deploy. do not auto-refresh without permission.
If the deploy mode is mixed (docker for some services, script for others): break the deploy steps into per-service groups. verify that all services deploy successfully before proceeding to healthcheck. if one service fails, stop and report which service failed and roll back all services or ask for manual intervention.
If the deploy mode is CI and CI is not accessible (network, auth, api rate limit): stop. ask the user to check ci system status or provide an alternative deploy method. do not fall back to manual deployment without asking.
If the switch method is cloudflare or load balancer api and credentials are missing or invalid: stop. ask the user to provide or refresh credentials from the secret store. do not ask the user to type credentials inline.
Config file (.bluegreenpilot/config.yaml):
yaml format, versioned in repo, contains topology (environments, slots, urls), deploy modes, switch method, rollback method, healthcheck path, database policy, and state backend location. secrets not stored here.
State files (.bluegreenpilot/state.<env>.yaml):
yaml format, per-environment, contains active_slot, inactive_slot, current_release, last_switch_time, healthcheck_status, and rollback_metadata. stored in state backend (repo, ci artifact, object storage, or manual).
History files (.bluegreenpilot/history/<timestamp>.<env>.yaml):
append-only yaml records, one entry per operation (deploy, switch, rollback). each entry includes operation type, source/release, active slot before/after, healthcheck result, switch method, approval timestamp, and user context.
Deploy plan (shown to user before approval): structured text or yaml with sections: target environment, current active slot, deploy target (inactive slot), source, database policy, pre-flight checks, deploy steps, verification, switch plan, rollback plan, unknowns/blockers.
Switch plan (shown at production gate): includes current active slot, proposed new active slot, release/commit id, healthcheck status, switch method, rollback command in full text, and explicit confirmation prompt.
Status report: shows target environment, active slot, current release id, last switch time, healthcheck status, and recent history (last 5-10 entries).
Audit log: reverse chronological list of all operations (deploy, switch, rollback) with timestamps, sources, slots, users, and outcomes.
the user knows the skill worked when:
Config initialized: user confirms they see .bluegreenpilot/config.yaml in their repo with the correct topology, environments, deploy modes, switch methods, and state backend.
State read successfully: skill reports current active slot, current release id, and healthcheck status for the target environment. if state is missing, skill asks how to retrieve it and does not proceed.
Plan generated and shown: skill displays a deploy or switch plan that includes deploy target, source, database policy, pre-flight checks, deploy steps, healthcheck steps, switch method