deploy-workflow

Deploy Workflow

Deployment of a Drupal site has a fixed order of operations. Skipping a step or reordering it produces failures that only surface at runtime. This skill enforces the sequence and its preconditions.

When this activates

• Deploying a Drupal codebase to staging or production
• Running a release on a multisite platform
• Applying core or contrib updates on a server
• The user asks to push changes live or update an environment

Phase 0 — Pre-flight (before touching the target)

1. Confirm the target: which environment, which drush alias or SSH host. Never assume production.
2. Verify the working tree being deployed is clean and on the intended tag/branch.
3. Check config status on the target: drush config:status. Unexpected overrides on the target mean someone changed config in the UI — resolve before deploying, or the import will silently destroy their changes.
4. Maintenance window: for schema-changing releases, ask whether maintenance mode is required (drush state:set system.maintenance_mode 1).

Exit condition: target confirmed by the user, config status reviewed.

Phase 1 — Backup

drush @TARGET sql:dump --result-file=auto --gzip

Also snapshot the current codebase reference (deployed tag/commit) so rollback is a known state, not a guess.

Exit condition: a restorable database dump exists and its location is recorded.

Phase 2 — Deploy sequence

The canonical order:

git fetch && git checkout TAG            # or the platform's deploy mechanism
composer install --no-dev --optimize-autoloader
drush deploy                             # = updb + cim + cr + deploy:hook (Drush 10.3+)

If drush deploy is not available or the project needs explicit control:

drush updb -y        # database updates first — update hooks may rely on old config
drush cim -y         # import configuration
drush cr             # rebuild caches
drush deploy:hook -y # post-deploy hooks, if used

Notes:

• If an update hook depends on new config being present, that is a design smell — prefer hook_post_update or hook_deploy_NAME(); do not hand-reorder cim before updb as a workaround without understanding why.
• Multisite: run the update sequence per site: drush -l SITE updb -y && drush -l SITE cim -y && drush -l SITE cr for every site sharing the codebase. A release is not done until every site has been updated.