Skip to content
Skills Library
DevOps & cloud · Automation

deploy

/deploy

Deploy one or more Magento 2 modules with pre-flight validation, ordered execution, smoke testing, and rollback on failure. Use when the user wants to deploy changes, enable a new module, run setup:upgrade after a code change, or roll back a previous deploy. Supports environment targets (local, staging, production) and produces a deploy report. Used by magento2-tools:feature, magento2-tools:fix, and magento2-tools:upgrade for their D* deploy step.

Licence
MIT
Last repository change
04.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
13
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/execute-plan.sh, scripts/preflight.sh, scripts/smoke.sh, scripts/snapshot.sh

What it does and when to use it

Deploy one or more Magento 2 modules with pre-flight validation, ordered execution, smoke testing, and rollback on failure. Use when the user wants to deploy changes, enable a new module, run setup:upgrade after a code change, or roll back a previous deploy. Supports environment targets (local, staging, production) and produces a deploy report. Used by magento2-tools:feature, magento2-tools:fix, and magento2-tools:upgrade for their D* deploy step.

Original author description

Deploy one or more Magento 2 modules with pre-flight validation, ordered execution, smoke testing, and rollback on failure. Use when the user wants to deploy changes, enable a new module, run setup:upgrade after a code change, or roll back a previous deploy. Supports environment targets (local, staging, production) and produces a deploy report. Used by magento2-tools:feature, magento2-tools:fix, and magento2-tools:upgrade for their D* deploy step.

How it works

  1. Core Rules
  2. Workflow
  3. Reference Files
  4. Templates
  5. Scripts
  6. Inputs
  7. Outputs
  8. Acceptance Criteria
  9. Notes on Safety
  10. Related Skills
Original SKILL.md headings · 270 lines, 1,785 words
SKILL.md preview
---
name: deploy
version: 1.5.0
description:
  Deploy one or more Magento 2 modules with pre-flight validation, ordered execution,
  smoke testing, and rollback on failure. Use when the user wants to deploy changes,
  enable a new module, run setup:upgrade after a code change, or roll back a previous
  deploy. Supports environment targets (local, staging, production) and produces a
  deploy report. Used by magento2-tools:feature, magento2-tools:fix, and
  magento2-tools:upgrade for their D* deploy step.
---

# Magento 2 Deploy

Coordinate the Magento deploy sequence safely. Validate before, execute in order, smoke
test after, and roll back on any failure.

## Core Rules

- **Never deploy without validation.** Pre-flight checks must pass before any
  state-modifying command runs. See `references/pre-flight-checks.md`.
- **Atomic by failure class.** A failure in `setup:upgrade` halts the sequence; the skill
  does not attempt later steps in the chain.
- **Rollback by recipe.** Each step that can fail has an explicit rollback recipe — see
  `references/rollback-recipes.md`.
- **One environment at a time.** Multi-env deploys are sequential
  (local → staging → production), gated on explicit user approval between environments.
  See `references/multi-env-protocol.md`.
- **Production gating.** Deploys to production require: an explicit `--env=production`
  flag AND an interactive confirmation. `--auto --env=production` is rejected unless
  `--i-know-what-im-doing` is also passed.
- **Snapshot before high-risk steps.** Offer a snapshot (`--snapshot`) before any
  production deploy. The snapshot captures `generated/`, `var/`, optionally `vendor/`.
- **Reports are written before state changes commit.** If the skill crashes mid-deploy,
  the report folder shows where it stopped.
- **Output budget.** Follow `context/references/output-budget.md` — targeted reads, summary-first test/lint output, long logs to files.

## Workflow

### Phase 0 — Context Resolution

Invoke `context`. Capture `runner`, `magento_cli`, `composer`. If `magento_cli`
is null, the deploy cannot proceed — abort with "no Magento CLI available; deploy
requires `bin/magento`."

### Phase 1 — Pre-flight Validation

Run **without modifying state**. See `references/pre-flight-checks.md` for the full
catalogue. Required by default:

| Check                      | Command                                                         | When required               |
|----------------------------|-----------------------------------------------------------------|-----------------------------|
| Module files exist         | `registration.php` in the module's dir — `app/code`, else the `vendor/` or `dev-packages/` package that declares it | All deploys |
| Composer validate          | `composer validate --no-check-publish` per module composer.json | All deploys                 |
| PHPCS Magento2             | `{runner} vendor/bin/phpcs --standard=Magento2 {modules}`       | If `--strict`               |
| PHPStan level 8            | `{runner} vendor/bin/phpstan analyse --level=8 {modules}`       | If `--strict`               |
| Unit tests                 | `{runner} vendor/bin/phpunit {modules}/Test/Unit`               | All deploys                 |
| Disk space                 | `df -h $(pwd)`                                                  | All deploys (warn at < 1GB) |
| Git working tree clean     | `git status --porcelain`                                        | Production only             |
| No pending DB declarations | `{magento_cli} setup:db:status`                                 | All deploys                 |
| Composer install dry-run   | `composer install --no-dev --dry-run`                           | Production only             |

Any required check failing aborts the deploy with a clear report. Run via
`${CLAUDE_SKILL_DIR}/scripts/preflight.sh`.

### Phase 2 — Plan

Build the **deploy plan** as an ordered list of commands. Use the template matching the
target environment from `references/deploy-plan-templates.md`.

Default plan (local/staging):

```
1. {magento_cli} module:status {modules}                       # Verify state
2. {magento_cli} module:enable {modules}
3. {magento_cli} setup:upgrade
4. For each persistence module: setup:db-declaration:generate-whitelist --module-name=X
5. {magento_cli} cache:flush
6. {magento_cli} indexer:status                                # Report invalid indexers
```

Production plan additionally includes (in order):

```
1. maintenance:enable
... (steps from default)
5b. {magento_cli} setup:di:compile
5c. {magento_cli} setup:static-content:deploy -f
6.  {magento_cli} cache:flush
7.  {magento_cli} indexer:reindex                              # invalid indexers only
8.  {magento_cli} queue:consumers:start                        # new consumers only
9.  maintenance:disable
```

Present the plan. Wait for explicit "proceed" unless `--auto` is set (and `--env` is
not `production`).

### Phase 3 — Execute

Run each command in order via `${CLAUDE_SKILL_DIR}/scripts/execute-plan.sh` or by direct shell:

- Capture exit code, stdout, stderr per command.
- Exit code != 0: STOP. Invoke rollback (Phase 4).
- Exit code 0 with warnings on stderr: log them, continue.
- Update the in-progress report file after every step so a crash leaves an auditable
  partial state.

### Phase 4 — Rollback Recipes (per failed step)

Triggered only on failure during Phase 3. See `references/rollback-recipes.md` for the
authoritative table.

| Failed step                   | Rollback recipe                                                                            |
|-------------------------------|--------------------------------------------------------------------------------------------|
| `module:enable`               | `module:disable {modules}`                                                                 |
| `setup:upgrade`               | Restore the DB dump (see below), `git revert <deploy commit>`, then re-run `setup:upgrade` |
| `setup:di:compile`            | Restore `generated/` from snapshot (if `--snapshot` was set)                               |
| `setup:static-content:deploy` | Re-run from previous version's git ref                                                     |
| `cache:flush`                 | Idempotent — no rollback needed                                                            |
| `indexer:reindex`             | Mark indexers invalid; re-run after the underlying issue is fixed                          |
| `queue:consumers:start`       | `queue:consumers:stop {consumer}`; clear bad messages                                      |

**`setup:upgrade` rollback is lossy without a DB backup.** Reverting code and re-running
`setup:upgrade` does NOT undo schema or data changes already applied:

- Applied **data patches** are recorded in `patch_list` and will be neither re-applied nor
  reverted by `setup:upgrade` (unless they implement `PatchRevertableInterface` and the
  module is uninstalled).
- **Declarative-schema** column/table drops are destructive — the data is gone and cannot
  be recovered from code.

To roll the database back you need a dump taken *before* the deploy: run the snapshot with
`--include-db` (writes `db-{ts}.sql.gz`) and restore it before re-running `setup:upgrade`:

```
gunzip < db-{ts}.sql.gz | MYSQL_PWD=<pass> mysql -h <host> -P <port> -u <user> <dbname>
```

Rollback is best-effort. Report exactly what was rolled back and what wasn't, with file
paths and commands for manual completion.

### Phase 5 — Smoke Tests

Run smoke tests appropriate to the modules deployed. See `references/smoke-tests.md`.

| Surface                          | Smoke                                                                                     |
|----------------------------------|-------------------------------------------------------------------------------------------|
| Any                              | `{magento_cli} module:status` shows all expected modules enabled                          |
| Any                              | `{magento_cli} setup:db:status` shows "Magento Database is up to date"                    |
| `service_contracts` + `rest_api` | `curl -s {host}/rest/V1/{vendor}/{route}/` returns 200/401 (not 500)                      |
| `graphql`                        | `curl -s -X POST {host}/graphql -d '{"query":"{__schema{queryType{name}}}"}'` returns 200 |
| `admin_ui`                       | `curl -s {host}/<frontName>/` returns 302 (login redirect) — frontName from `ADMIN_PATH`, else `app/etc/env.php`; a 404 on a guessed `/admin/` is skipped, not failed |
| `frontend_ui`                    | `curl -s {host}/{vendor_lower}_{module_lower}/{route}/` returns expected status           |
| `cron`                           | crontab installed (`crontab -l \| grep cron:run`) + `cron_schedule` has recent rows (no `cron:status` command exists) |
| `queue`                          | `{magento_cli} queue:consumers:list` shows new consumers registered                       |
| Any                              | no `var/report/**` file and no module-attributed ERROR+ `var/log/*.log` entry since the deploy started — two of Magento's three error sinks never write to `exception.log` |

A smoke failure does NOT trigger rollback (the deploy completed) but is reported as a
"needs investigation" finding. Run via `${CLAUDE_SKILL_DIR}/scripts/smoke.sh`, passing
`SINCE_TS` (the Phase 3 start timestamp), `MAGENTO_ROOT`, `MODULES` and `BASE_URL` — without
`SINCE_TS` the error-signal scan silently widens to a 15-minute window. `MAGENTO_ROOT` is also
where the admin frontName is read from; pass `ADMIN_PATH` when it is not there. HTTPS certificates
are verified except on `localhost`, `*.localhost`, `*.test` and loopback hosts, or when
`SMOKE_CURL_INSECURE=1`.

### Phase 6 — Report

Write to `{output_root}/deployments/{YYYY-MM-DD-HHMMSS}-{env}.md` AND the JSON sibling,
where `{output_root}` is the `--docs-root` value when the caller passed one, else
`{ctx.docs_root}` (see "Output Root" below). Use `templates/report.md`. Sections:

- Modules deployed (table with version, status)
- Environment
- Pre-flight results
- Plan executed (with timing per step)
- Per-step results (exit code, stdout digest, stderr digest)
- Smoke test results
- Failures + rollbacks (if any)
- Total time + bytes shifted
- Skill versions

## Reference Files

- `references/pre-flight-checks.md` — full pre-flight check catalogue.
- `references/deploy-plan-templates.md` — per-environment plan templates.
- `references/rollback-recipes.md` — per-step rollback procedures.
- `references/smoke-tests.md` — surface-driven smoke test catalogue.
- `references/multi-env-protocol.md` — local → staging → production gating.
- `references/maintenance-mode.md` — when to enable/disable maintenance mode.

## Templates

- `templates/report.md` — deploy report template (Markdown).
- `templates/plan.md` — pre-execution plan template (printed for user approval).

## Scripts

- `${CLAUDE_SKILL_DIR}/scripts/preflight.sh` — run pre-flight checks; emit JSON pass/fail summary.
- `${CLAUDE_SKILL_DIR}/scripts/execute-plan.sh` — execute a plan file step-by-step, log per-step results.
- `${CLAUDE_SKILL_DIR}/scripts/smoke.sh` — run smoke tests for given module list.
- `${CLAUDE_SKILL_DIR}/scripts/snapshot.sh` — create a pre-deploy snapshot of `generated/`, `var/`, optionally
  `vendor/` (`--include-vendor`) and the database (`--include-db`, required for a non-lossy `setup:upgrade` rollback).

## Inputs

```
/deploy [--env=local|staging|production] [--strict] [--auto] [--snapshot] [--full] [--validate-only] [--docs-root=<path>] <Vendor>_<Module>...
```

| Flag                     | Default                               | Meaning                                                                                                                                                                      |
|--------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--env`                  | `local`                               | Target environment. `production` requires interactive confirm.                                                                                                               |
| `--strict`               | off                                   | Require PHPCS + PHPStan to pass in pre-flight.                                                                                                                               |
| `--auto`                 | off                                   | Skip approval gate before Phase 3. Rejected on production unless `--i-know-what-im-doing`.                                                                                   |
| `--snapshot`             | off (local/staging) / prompted (prod) | Snapshot before deploy for rollback.                                                                                                                                         |
| `--full`                 | off (local/staging) / on (prod)       | Run optional steps (maintenance, static-deploy, di:compile).                                                                                                                 |
| `--validate-only`        | off                                   | Run **only** Phase 0 (context) + Phase 1 (pre-flight) + Phase 2 (plan). Skip Phase 3 onwards. Exit 0 if all required checks pass, 1 otherwise. Safe for release / CI gating. |
| `--i-know-what-im-doing` | off                                   | Required for `--auto --env=production` combination.                                                                                                                          |
| `--docs-root=<path>`     | unset                                  | Output-root override; see "Output Root" below.                                                                                                                              |

**Implementation note for `--validate-only`:** when this flag is set, the skill MUST exit after writing the validation
report. No `setup:upgrade`, no cache flush, no static-content:deploy, no maintenance toggling. The validation report
follows the same `{output_root}/deployments/{timestamp}-{env}.{md,json}` layout but with `"mode": "validate-only"` in the JSON
and a `Validation only — no deploy executed` banner in the markdown.

## Outputs

```
{output_root}/deployments/{timestamp}-{env}.md                # Markdown report
{output_root}/deployments/{timestamp}-{env}.json              # Machine-readable for CI
{output_root}/deployments/{timestamp}-{env}.snapshot.tar.gz   # Optional snapshot for rollback
```

`{output_root}` (`.docs` by default, `{ctx.docs_root}`) is anchored at the project root,
never under `{ctx.magento_root}`, `app/code`, or a module dir. See the **Artifact location**
rule in `context/SKILL.md`.

### Output root (`--docs-root`)

This skill has an inline emitter (no `build-findings.sh`): the pre-flight, execute-plan,
smoke, and snapshot scripts already take their output path from caller-supplied
`OUTPUT_FILE`/`OUTPUT_DIR` env vars or arguments, so no script changes were needed. The
skill itself accepts `--docs-root=<path>` (see
`context/references/artifact-layout.md`) and, when set, writes the Markdown +
JSON report and invokes `snapshot.sh <path>/deployments` (the script's output dir is a
positional argument, not an env var) so all deploy artifacts land under
`<path>/deployments/`; otherwise they default to `{ctx.docs_root}/deployments/`.
Orchestrators such as `feature` pass this to collect a run's
artifacts under one folder.

## Acceptance Criteria

- Aborts on any required pre-flight failure with a clear list of failed checks.
- Never proceeds to production without explicit interactive confirmation.
- Rollback restores the prior known-good state for any failure during `module:enable`,
  `setup:upgrade`, or `setup:di:compile`.
- Smoke tests run for every applicable surface.
- Report contains enough information to re-deploy or roll back without consulting the
  skill again.

## Notes on Safety

- **Default-deny on destructive steps.** Production deploys require both a flag and an
  interactive confirm.
- **No flag combination silently does dangerous things.** `--auto --env=production`
  rejected unless `--i-know-what-im-doing` is also set.
- **Reports are written before state changes commit.** If the skill crashes mid-deploy,
  the report folder shows where it stopped.
- **Snapshots are opt-in but offered every time on production.** The first prompt in
  production deploys asks "snapshot before deploy? (y/n)".

## Related Skills

| Caller                       | Use                                                        |
|------------------------------|------------------------------------------------------------|
| `feature` | Phase 5 D1 task                                            |
| `fix`           | Phase 6 (optional)                                         |
| `upgrade`    | After upgrade is patched                                   |
| `release`           | Phase 2 (validate only — `--strict` pre-flight)            |
| Direct user                  | `/deploy --env=staging Acme_ModuleA Acme_ModuleB` |
Files in this package (13)
  • SKILL.md 17 KB
  • references/deploy-plan-templates.md 3 KB
  • references/maintenance-mode.md 2 KB
  • references/multi-env-protocol.md 3 KB
  • references/pre-flight-checks.md 5 KB
  • references/rollback-recipes.md 3 KB
  • references/smoke-tests.md 8 KB
  • scripts/execute-plan.sh 3 KB
  • scripts/preflight.sh 33 KB
  • scripts/smoke.sh 14 KB
  • scripts/snapshot.sh 5 KB
  • templates/plan.md 1 KB
  • templates/report.md 3 KB

Versions

RepositoryScoreLicence
This page · muon-m2/magento2-tools100MIT
zeitlos/lucity100AGPL-3.0
jeremylongshore/tons-of-skills-marketplace100MIT
zeitlos/lucity100AGPL-3.0
microsoft/power-platform-skills100MIT
friendlyinternet/nuxt-crouton100MIT
wraith-proxy/wraith-skills100MIT
jikig-ai/soleur100Apache-2.0
curiositech/windags-skills100Apache-2.0

Database snapshot: 13.11.2026 · package version 83afe3768b4e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100deployment-sop
    Deployment workflows, pre-deploy validation, and smoke testing patterns. Use when deploying to staging or production, running smoke tests, or validating deployments.
  • 100deployment-sop
    Deployment workflows, pre-deploy validation, and smoke testing patterns. Use when deploying to staging or production, running smoke tests, or validating deployments.
  • 90staging-deployment
    Deploy and verify software in a staging or testing environment. Use when DevOps must promote a build beyond local deployment, run staging smoke checks, coordinate SSH/Docker/Kubernetes staging rollout, preserve rollback evidence, and produce a deploy report without exposing…
  • 100magento-deploy
    Deploy Magento 2 — deployment modes, static content deployment, DI compilation, CLI commands, zero-downtime strategies, and CI/CD pipeline setup. Use when preparing for production deployment or building deployment automation.
  • 100deploy-qa
    Sync development into QA/testing environment branches (QA1-QA4, local RH staging) via PR + merge on GitHub. Use when deploying/promoting the latest development code to any HMIS QA instance or the local RH staging environment.
  • 100envoyer-deploy
    Deploy a project with Envoyer (envoyer.io) and follow it to the end. Triggers the deploy hook for an environment (staging by default, production after confirmation), optionally for a given commit or branch, waits for the deployment to finish and reports it. Optional steps make…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.