Upgrade to New Version

Upgrade Process

Critical: Require Version Range

Version Range Format

Example: Upgrading to Magento 2.3.2

"require": {
    "magento/magento-cloud-metapackage": ">=2.3.2 <2.3.3"
}

Flexibility for Updates

What This Enables

Step-by-Step Process

Step 1: Update composer.json

# Edit composer.json
"require": {
    "magento/magento-cloud-metapackage": ">=2.4.6 <2.4.7"
}

Step 2: Run composer update

# Update dependencies
composer update magento/magento-cloud-metapackage --with-dependencies

Step 3: Commit Changes

git add composer.json composer.lock
git commit -m "Upgrade Magento to 2.4.6"

Step 4: Push to Integration

# Push to integration first
git push origin integration

# Test thoroughly
# Verify functionality
# Check logs

Step 5: Merge to Staging

# After testing in integration
git checkout staging
git merge integration
git push origin staging

# Test in staging
# Full regression testing

Step 6: Deploy to Production

# After successful staging tests
git checkout master  # or production for Pro
git merge staging
git push origin master

# Monitor production deployment
# Verify site functionality

Common Upgrade Scenarios

Upgrade to 2.4.6

"magento/magento-cloud-metapackage": ">=2.4.6 <2.4.7"

Upgrade to 2.4.5

"magento/magento-cloud-metapackage": ">=2.4.5 <2.4.6"

Upgrade to 2.3.7

"magento/magento-cloud-metapackage": ">=2.3.7 <2.3.8"

Cloud Deployment Tools

Explicit ece-tools Upgrade

# If needed, specify ece-tools version
composer require magento/ece-tools:^2002.1.0 --no-update
composer update magento/ece-tools --with-dependencies

Full Workflow: 2.4.5 to 2.4.6

1. Prepare Local Environment

# Create feature branch
git checkout -b upgrade-2.4.6
git pull origin master

2. Update composer.json

# Edit composer.json
{
    "require": {
        "magento/magento-cloud-metapackage": ">=2.4.6 <2.4.7",
        "magento/ece-tools": "^2002.1.0"
    }
}

3. Run Composer Update

composer update magento/magento-cloud-metapackage --with-dependencies

# Review output
# Check for conflicts
# Resolve any issues

4. Test Locally (Optional)

bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Test basic functionality

5. Commit and Push to Integration

git add composer.json composer.lock
git commit -m "Upgrade Magento Cloud to 2.4.6"
git push origin upgrade-2.4.6

# Create pull request or merge to integration

6. Monitor Integration Deployment

# Watch deployment logs
magento-cloud log deploy -e integration

# SSH and verify
magento-cloud ssh -e integration
bin/magento --version  # Should show 2.4.6

7. Test Integration

• Frontend functionality
• Admin panel access
• Checkout process
• Third-party integrations
• Custom modules

8. Merge to Staging

git checkout staging
git merge upgrade-2.4.6
git push origin staging

9. Full Staging Tests

• Regression testing
• Performance testing
• UAT (User Acceptance Testing)
• Third-party service verification

10. Deploy to Production

# Schedule maintenance window
# Create production snapshot
magento-cloud snapshot:create -e production

# Merge to production
git checkout master
git merge staging
git push origin master

# Monitor production deployment
# Verify site is live and functional

Before You Upgrade

After Deployment

Verify Version

# SSH to environment
magento-cloud ssh -e staging

# Check Magento version
bin/magento --version

# Check ece-tools version
composer show magento/ece-tools | grep versions

Check Functionality

• ✅ Homepage loads correctly
• ✅ Admin login works
• ✅ Product pages display
• ✅ Checkout process completes
• ✅ Payment gateways work
• ✅ Shipping methods available
• ✅ Email notifications sent
• ✅ Cron jobs running
• ✅ Third-party integrations functional

Monitor Logs

# Check for errors
tail -f /var/log/error.log
tail -f /app/var/log/exception.log
tail -f /app/var/log/system.log

Common Issues

Issue 1: Composer Conflicts

Issue 2: Deployment Failures

Upgrade Guidelines