Adobe Commerce Patching Automation workflow overview

This topic provides a high-level overview of how patch operations work using Adobe Commerce Patching Automation.

Terminology

Operations

Patching Automation supports two main operations for managing patches in your Adobe Commerce Cloud environment:

Phases

The Patching Automation workflow uses three phases that are always executed in this order to ensure that patches are applied safely and reliably:

Phase details

Phase 1: Preliminary check

The Preliminary Check phase validates that the patch can be safely applied to your environment.

What happens:

Phase 2: Patching

The Patching phase applies or reverts the patch in a temporary integration environment. During this stage, the service creates a temporary integration environment to safely apply the patch, confirm it deploys successfully, and verify it passes a health check — before making any changes to your actual environment.

This approach provides:

Stage 2a: Integration environment creation

Branch creation - Patching Automation creates a temporary integration environment branch named {target-environment}-CAPS-{patch-id}

Environment setup - The integration environment is created as a child of your target environment

Code synchronization - The integration environment inherits the exact code state of your target environment (the same codebase)

No data cloning - The integration environment does not receive a copy of the target environment’s data (database, media, or other stored content)—only the codebase is used to apply and verify the patch

Resource requirements - Your Cloud project’s total storage capacity is defined in your contract. (Check via your account page or magento-cloud subscription:info). Each environment’s disk allocation is configured separately, via the disk property in .magento.app.yaml/.magento/services.yaml. See Manage disk space for details. If a patch operation fails due to storage limitations, check your integration environment’s disk usage (magento-cloud db:size / magento-cloud mount:size) against its configured allocation.

Stage 2b: Patch application in integration environment

Safe testing - The patch is applied to the integration environment, not directly to your target environment

File management - Patch files are placed in the m2-hotfixes folder

Git operations - Changes are committed and pushed to the integration environment branch

Environment activation - The integration environment is activated to deploy the patched code

Health check - Once activated, Patching Automation confirms the following before proceeding to merge: the integration environment deployed successfully and is healthy, the application starts, and its database and cache connections are reachable.

Stage 2c: Merge back to target environment

Sync check - Before merging, the service confirms that the integration environment is still active, in sync with the target environment, and healthy. If the target has changed during patching, the operation stops here instead of merging

Environment checkout - The service checks out your target environment locally

Merge operation - The integration environment branch is merged into the target environment

Conflict handling - If a merge conflict occurs, the operation fails and is reported as an error — it is not resolved automatically

Deployment - The merged changes are deployed to your target environment

Verification - The service verifies that the merge was successful and the environments are in sync

Integration environment lifecycle

Integration environments have a specific lifecycle during the patching stage:

Phase 3: Validation

The Validation phase confirms that the patched application starts successfully and passes a health check.

What happens:

Success indicators

Apply operation:

Revert operation:

Production environment safeguards

Applying or reverting patches on a production environment carries more risk than on other environments, so Patching Automation includes two safeguards specific to production.

Confirmation before starting

Before any apply or revert operation starts on a production environment, you’re prompted to confirm the operation in a dialog. This confirmation step protects against accidentally starting a job on production.

Recommended preconditions

Adobe recommends enabling maintenance mode and disabling cron jobs before patching a production environment. By default, Patching Automation verifies that both conditions are met and blocks the operation with a notification if either condition is not met. If you understand the risks of proceeding without maintenance mode or with cron jobs enabled, select the override checkbox in the UI to bypass this check.

Related topics