Upgrade Commerce version

To install or update services in Staging and Production environments only, submit an Adobe Commerce Support ticket.

In the ticket, specify the required service changes, include the updated .magento.app.yaml and .magento/services.yaml files and note the target PHP version.

PHP version, Composer updates, extensions, and environment settings are self-service changes. Adobe may need to update the New Relic agent for PHP version compatibility. See PHP settings in Application configuration.

Confirm the upgrade schedule through Adobe’s two-part process: you confirm the requested date and time first, then Support submits it to the Infrastructure team for final confirmation.

Production changes (Pro only) require at least two business days’ notice, excluding weekends. For example, the Cloud Infrastructure team must acknowledge a Monday upgrade by the preceding Wednesday. Expect additional lead time during peak demand. To avoid delays, respond to the initial request at least 48 hours before the window. The upgrade is not considered scheduled until you receive final confirmation.

Validate the upgrade in a Staging or Integration environment before scheduling it in Production.

Issues caused by third-party modules, custom code, or dependency compatibility often surface during the redeployment that follows a service upgrade. To validate multiple service upgrades one at a time, a reasonable order is Valkey or Redis, then RabbitMQ, then OpenSearch, then MariaDB. This is not a required sequence. Database upgrades carry the highest operational impact and deserve the most caution.

Adobe does not guarantee the exact duration of a Production maintenance window in advance, since timing depends on the environment and the services involved. Use the time your Staging upgrade takes as a practical estimate when planning the Production window.

Redeploy the environment after Adobe completes the service upgrade so the change takes effect, even if the Adobe Commerce application version does not change.

If the upgrade includes OpenSearch, also plan for a full reindex. Adobe cannot guarantee zero downtime for a service upgrade, so plan a maintenance window that allows time to redeploy, reindex if needed, and validate the storefront and Admin before reopening the site.

Add the following allow-plugins to the config section:

"config": {
   "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "laminas/laminas-dependency-plugin": true,
      "magento/*": true
   }
},

Add the following plugin to the require section:

"require": {
    "magento/composer-root-update-plugin": "^2.0.3"
},

Add the following component to the extra:component_paths section:

"extra": {
   "component_paths": {
      "tinymce/tinymce": "lib/web/tiny_mce_5"
   },
},

Save the file. Do not commit or push changes to your branch yet.

Continue with the upgrade process.

Create a local backup of the remote database.

magento-cloud db:dump

Back up code and media.

php bin/magento setup:backup --code [--media]

Optionally, you can omit [--media] if you have a large number of static files that are already in source control.

Use SSH to log in to the remote environment.

Create a database dump. To choose a target directory for the DB dump, use the --dump-directory option.

vendor/bin/ece-tools db-dump

The dump operation creates a dump-<timestamp>.sql.gz archive file in your remote project directory. See Back up database.

On your local workstation, change to your project directory.

Set the version constraint for the target upgrade version. This step is only necessary if the target version is outside the existing constraint.

composer require-commerce "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update

Update your composer.json file with the core Commerce upgrade version.

composer require-commerce magento/product-enterprise-edition 2.4.8 --no-update

If you’re using B2B, update your composer.json file with the supported version for Commerce.

composer require-commerce magento/extension-b2b 1.5.2 --no-update

Update project dependencies.

composer update

Review the patches that are currently applied:

• If there are any patches installed in the m2-hotfixes directory, submit an Adobe Commerce Support ticket and work with Adobe Commerce Support to verify which patches can still be applied to the new version. Remove the non-applicable patch(es) from the m2-hotfixes directory.

• If there are any [Quality Patches] applied in the .magento.env.yaml file, verify whether they can still be applied to the new version. Remove the non-applicable patch(es) from the QUALITY_PATCHES section of the .magento.env.yaml file.

Method 1: Verify the applicable versions in the Quality Patches release notes

Method 2: View available patches and status

Method 3: Search for patches

Add, commit, and push code changes.

git add -A

git commit -m "Upgrade"

git push origin <branch-name>

git add -A is required to add all changed files to source control because of the way Composer marshals base packages. Both composer install and composer update marshal files from the base package (magento/magento2-base and magento/magento2-ee-base) into the package root.

The files that Composer marshals belong to the new version of Adobe Commerce, to overwrite the outdated version of those same files. Currently, marshaling is disabled in Adobe Commerce, so you must add the marshaled files to source control.

To complete the upgrade, wait for deployment.

Verify the upgrade in your Integration, Staging, or Production environment by using SSH to log in and check the version.

php bin/magento --version

Create a branch on your local workstation.

Disable your extensions as needed.

When available, download extension upgrades.

Install the upgrade as documented by the third-party documentation.

Enable and test the extension.

Add, commit, and push the code changes to the remote.

Push to and test in your integration environment.

To test in a pre-production environment, push to the Staging environment.

On your local workstation, change to your project directory.

Use SSH to log in to the remote environment.

magento-cloud ssh

Open the ./app/var/report/<error number> file.

Examine the logs and determine the source of the issue.

Add, commit, and push code changes.

git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>