Keeping your Adobe Commerce (Magento 2) store secure and updated is vital for smooth operations. One of the key ways to do this is by applying patches properly. Whether you’re working with Adobe Commerce on Cloud infrastructure or managing an on-premise environment, understanding how patching works is essential for every developer.
In this blog post, I will guide you—step-by-step—on how to apply patches in Adobe Commerce, especially in Cloud environments, using best practices as a Magento 2 developer.
What Are Patches in Adobe Commerce?
Patches are code-level changes that fix bugs, improve features, or close security vulnerabilities. Adobe offers three types of patches:
1. Cloud Patches for Adobe Commerce
These are required patches automatically delivered via the magento/magento-cloud-patches package. They are applied during deployment using ece-tools.
2. Quality Patches
These are optional patches provided through the Quality Patches Tool (QPT). You can apply specific patches based on your store’s needs without affecting backward compatibility.
3. Custom Patches
These are project-specific fixes added manually by developers to the /m2-hotfixes/ directory in the project root.
Prerequisites Before You Start
Before applying any patches:
- Always create a dedicated branch from the Integration environment to avoid conflicts.
- Ensure you’re using
ece-toolsversion 2002.1.2 or above. - Install the latest version of the Quality Patches Tool via Composer if needed.
How to View Available Patches
To see the list of available and applied patches:
php ./vendor/bin/ece-patches statusThis command shows:
- Patch ID
- Title
- Type (Required / Optional / Deprecated / Custom)
- Status (Applied / Not Applied / N/A)
- Affected components
This helps you determine which patches are missing or require reapplication after an upgrade.
How to Apply Patches in Local Development
Follow these steps to apply patches in your local environment:
Step 1: Add Patch IDs to .magento.env.yaml
stage:
build:
QUALITY_PATCHES:
- MCTEST-1111
- MCTEST-2222Step 2: Run Patch Apply Command
php ./vendor/bin/ece-patches applyThis command applies patches in the following order:
- Required Cloud patches
- Selected optional patches
- Custom patches from
/m2-hotfixes
Step 3: Clear Cache
php bin/magento cache:cleanStep 4: Test the Results
Ensure all patches work as expected. Adjust custom patches if required.
This is recommended to run all deployment commands if patch has major changes.
How to Apply Patches in Cloud Environments
To apply patches on a Cloud instance:
Step 1: Add Patch IDs in .magento.env.yaml
stage:
build:
QUALITY_PATCHES:
- MCTEST-1111
- MCTEST-2222
Step 2: Commit and Push Changes
git add .magento.env.yaml
git commit -m "Apply quality patches"
git push origin <branch-name>
Tip: After each Adobe Commerce upgrade, check whether the patches are still required and reapply them if necessary.
How to Apply Custom Patches
Follow these steps to apply custom patches:
Step 1: Create Patch Directory (if it doesn’t exist)
mkdir m2-hotfixesStep 2: Add Your .patch Files
Place your patch files inside /m2-hotfixes/.
Step 3: Commit and Push
git add m2-hotfixes/
git commit -m "Apply custom patch"
git push origin <branch-name>Make sure to test these patches thoroughly in staging or integration environments.
How to Revert a Custom Patch
To uninstall or roll back a custom patch:
Step 1: Delete the Patch File
Remove the file from /m2-hotfixes/.
Step 2: Commit and Push Changes
git add m2-hotfixes/
git commit -m "Revert patch"
git push origin <branch-name>Revert All Patches in Local
To revert all applied patches (custom, optional, required) locally:
php ./vendor/bin/ece-patches revertPatch Logs
Patch operations are logged in:
<your_project_root>/var/log/patch.logYou can use this log to audit applied or reverted patches for troubleshooting.
Summary and Best Practices
- Always create a separate branch for patching.
- Apply patches in the correct order: Required → Optional → Custom.
- Reapply custom patches after upgrades.
- Test all patches in integration or staging environments.
- Log and document every applied patch.
If you’re a developer reading this, I highly encourage you to bookmark this guide and follow it during every patching cycle. Your future self (and your team) will thank you! 😜
You may also like this,
Magento 2: How to Apply Patch?
Adobe Commerce Cloud Project Structure
How to Apply Patches in Adobe Commerce (Magento 2 Cloud)