How the Cloud Automation Patching Service (CAPS) workflow works
This topic provides a high-level overview of how patch operations work using CAPS (Cloud Automation Patching Service).
Terminology
-
Operations - the main actions performed by CAPS:
- Apply
- Revert
-
Phases - the three phases of the workflow:
- Preliminary check
- Patching
- Validation
-
Environment - the Adobe Commerce Cloud environment where patches are applied.
Operations
CAPS supports two main operations for managing patches in your Adobe Commerce Cloud environment:
-
Apply operation - adds patch changes to your codebase through a safe, validated process. Patches are applied by placing patch files in the ‘m2-hotfixes’ folder.
-
Revert operation - removes previously applied patches from your codebase by removing patch files from the ‘m2-hotfixes’ folder.
Phases
The CAPS workflow uses three phases that are always executed in this order to ensure that patches are applied safely and reliably:
- Preliminary check - validates patch compatibility and environment readiness.
- Patching - applies or reverts the patch in an integration environment.
- Validation - validates the patch application and performs health checks.
Phase details
Phase 1: Preliminary check
The Preliminary Check phase validates that the patch can be safely applied to your environment.
What happens:
-
Production environment safeguards (Production environments only):
- Checks if store is in maintenance mode
- Verifies cron jobs are disabled
- Blocks patching if conditions are not met
- Displays confirmation dialog if conditions are met
-
Patch validation - verifies the patch file is valid and compatible
-
Environment assessment - checks environment readiness and resources
-
Conflict detection - identifies potential conflicts with existing code
-
Dependency check - validates Adobe Commerce version compatibility
Phase 2: Patching
The Patching phase applies or reverts the patch in a temporary integration environment for testing. During this stage, CAPS creates a temporary test environment to safely apply and test the patch before making changes to your actual environment.
This approach provides:
- Safety - keeps your target environment untouched until the patch is validated
- Testing - in a real environment before affecting production
- Rollback capability - if issues are detected
- Isolation - for each patch operation
Stage 2a: Integration environment creation
Branch creation - CAPS 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 state of your target environment
Resource requirements - CAPS creates a temporary environment using the codebase from your target environment. According to Adobe Commerce Cloud documentation, each environment (including integration environments) has separate storage allocation based on your contracted storage plan. The amount of storage you contracted represents the total storage for each environment. In most cases, you will not face any issues with resource limitations. If you encounter any error with resource limitations, please check your application size and your contracted storage in your plan.
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/ directory
Git operations - Changes are committed and pushed to the integration environment branch
Environment activation - The integration environment is activated to deploy the patched code
Stage 2c: Merge back to target environment
Environment checkout - CAPS checks out your target environment locally
Merge operation - The integration environment branch is merged into the target environment
Conflict resolution - If any conflicts occur, they are resolved automatically when possible
Deployment - The merged changes are deployed to your target environment
Verification - CAPS verifies that the merge was successful and the environments are in sync
Environment cleanup - The temporary integration environment is deleted to free up resources
Integration environment lifecycle
Integration environments have a specific lifecycle during the patching stage:
- Creation - Created at the start of the patching stage
- Active period - Remain active during patch application and testing
- Cleanup - Automatically deleted after successful merge or if the operation fails
Phase 3: Validation
The Validation phase ensures the patched application works correctly and performs health checks.
What happens:
- Application health check - verifies the application starts and runs properly
- Cleanup - removes temporary environment, updates logs, notifies completion
Success indicators
Apply operation:
- “Job completed successfully” - Patch applied without issues
- “Patch has been applied” - Patch was already present (no action needed)
- Patch file successfully placed in ‘m2-hotfixes’ folder
- All validation checks pass
- Application health checks successful
Revert operation:
- “Job completed successfully” - Patch reverted without issues
- “Patch has been reverted” - Patch was already reverted (no action needed)
- Patch file successfully removed from ‘m2-hotfixes’ folder
- All validation checks pass
- Application health checks successful
Production environment safeguards
CAPS includes specific safeguards for production environments to prevent accidental disruptions and ensure patches are safely validated beforehand.
Preconditions for production patching
Before applying patches to production environments, CAPS checks for two critical conditions:
- Maintenance mode - The store must be in maintenance mode
- Cron jobs disabled - Cron jobs must be disabled
If either condition is not met, the patch application is blocked and the user is notified.