Cloud 8.05

Branch Synchronization and Merge

Understanding sync, environment hierarchy, merge workflows, and conflict resolution.

Exam Critical: Understanding branch synchronization, environment hierarchy, and merge workflows is ESSENTIAL for the exam!

Branch Synchronization and Merge

mindmap root((Branch Sync & Merge)) Synchronization Load DB and code From parent branch Project Web UI Cloud CLI Hierarchy Starter structure Pro structure Parent child Upstream Repo Cloud is upstream GitHub GitLab BitBucket Git pull merge Merge in primary repo Merge Function Child to current Staging to production Starter vs Pro Resolve conflicts locally

Branch Synchronization and Merge Overview

Management Tools

Available Tools

The Project Web Interface and the Magento Cloud CLI provide a toolset to manage environments (aka branches).

  • Sync: Load database and code from parent
  • Merge: Promote code from child to parent
  • Activate/Deactivate: Control branch availability
  • Branch: Create new environments

Sync: Loading Data and Code

What is Synchronization?

Definition

Sync loads the database and code from a parent branch.

What Sync Does:
  • Database: Copies database from parent to child environment
  • Code: Pulls code changes from parent branch
  • Files: Can optionally sync uploaded files (media)
  • Overwrites: Replaces child environment data with parent's
Important:

Synchronization overwrites the child environment's database with the parent's. Any data in the child environment will be lost!

Understanding Environment Hierarchy

Git vs Cloud Hierarchy

Git Has No Hierarchy

In git, there is no concept of hierarchy. master is on the same plane as any other branch.

Cloud Adds Three-Dimensional Perspective

Cloud gives more of a three-dimensional perspective with parent-child relationships.

Starter Environment Hierarchy

Starter Plan Structure

Hierarchy:

Master
  └── Staging
        └── Integration environments
Explanation:
  • Master: Production environment
  • Staging: Child of Master
  • Integration: Children of Staging
Environment Parent Purpose Can Sync From
Master None Production site N/A
Staging Master Pre-production testing Master
Integration Staging Development branches Staging (or Master)

Pro Environment Hierarchy

Pro Plan Structure

Slightly Different from Starter

In Cloud Pro, this is slightly different:

Master (master branch - git reference)
Production (what serves content for visitors)
  └── Staging
        └── Integration
              └── Integration branches
Environment Description Purpose
Master master branch (git) Git reference, not deployed
Production What serves content Live site for visitors
Staging Child of Production Pre-production testing
Integration Parent integration branch Main development branch
Integration branches Children of Integration Feature branches
Key Difference:
  • Master branch: Git reference
  • Production environment: What visitors see
  • Staging syncs from Production (or Master)

Performing Synchronization

How to Sync Environments

With this idea, you can synchronize data from the Master environment back to Staging.

This is done either in the Project Web Interface or the Magento Cloud CLI.

Method 1: Project Web Interface

  1. Navigate to the environment you want to sync TO (e.g., Staging)
  2. Click Sync button
  3. Select what to sync:
    • ☑ Code - Pull code from parent
    • ☑ Data - Copy database from parent
  4. Click Sync
  5. Wait for synchronization to complete

Method 2: Magento Cloud CLI

# Sync current environment from parent
magento-cloud environment:synchronize

# Sync specific environment
magento-cloud environment:synchronize -e staging

# Sync only code (no data)
magento-cloud environment:synchronize --no-data

# Sync only data (no code)
magento-cloud environment:synchronize --no-code
Example: Sync Staging from Master
# Navigate to staging environment
magento-cloud environment:checkout staging

# Sync code and data from master
magento-cloud environment:synchronize

# Or specify parent explicitly
magento-cloud environment:synchronize -p master

Cloud as Upstream Repository

Using GitHub/GitLab/BitBucket

Critical Concept

If you are hosting your code in GitHub/GitLab/BitBucket, remember that Magento Cloud is, in effect, its own git repository that is upstream of your repository on GitHub.

Repository Relationship

Flow:
Your Local Repository
    ↓ (git push)
GitHub/GitLab/BitBucket (origin)
    ↓ (integration/webhook)
Magento Cloud Repository (upstream)
  • Cloud is upstream: Receives code from GitHub/GitLab
  • GitHub is origin: Your primary repository
  • Webhooks: Trigger Cloud deploys when you push to GitHub

Code Synchronization Mechanics

What Happens During Code Sync

Git Pull Under the Hood

Performing a synchronization of code is essentially a git pull origin master (for example) and merges code.

Potential Problems

This could cause problems, so it is ideal to do these merges in your primary git repository and don't use merging functionality in Cloud.

Why This Can Cause Issues:
  • Merge conflicts may occur
  • Cloud doesn't provide conflict resolution tools
  • Harder to track merge history
  • Less control over merge process
Best Practice:

Merge in your primary git repository (GitHub/GitLab/BitBucket) first, then push to Cloud. Don't use Cloud's merge functionality if using external git provider.

Practical Experience: Sync Data

Exercise: Synchronize Staging from Master

Required Practice:

Synchronize the data on staging from the master environment.

Step-by-Step Workflow

  1. Project Web Interface Method:
    • Navigate to Staging environment
    • Click "Sync" button
    • Select "Code" and "Data"
    • Click "Sync"
    • Wait for completion
  2. CLI Method: 
    magento-cloud environment:checkout staging
magento-cloud environment:synchronize
  3. Verify:
    • SSH to staging
    • Check database has master data
    • Verify code is updated
    • Test functionality

Merge: Promoting Code

Understanding Merge Function

What is Merge?

The merge function merges code in a child branch with that of the current branch.

Purpose:
  • Promote code from child environment to parent
  • Deploy tested code to production
  • Integrate feature branches
  • Standard git merge operation

Promoting to Production

Starter vs Pro Merge Workflows

Starter Projects

To promote staging code to production:

Merge staging into master

# Via CLI
magento-cloud environment:merge staging -e master

# Or via git
git checkout master
git merge staging
git push magento master

Master is production on Starter, so merging to master deploys to production.

Pro Projects

To promote staging code to production:

Merge staging into production

# Via CLI
magento-cloud environment:merge staging -e production

# Production is separate from master on Pro

Pro has separate Production environment, so merge staging into production (not master).

Merge Methods

Where to Perform Merges

Method When to Use Command/Process
Command Line Direct Cloud merges magento-cloud environment:merge
Project Web Interface NOT using external git provider Click "Merge" button
GitHub/GitLab/BitBucket Using external git provider (RECOMMENDED) Pull Request / Merge Request

Recommended Workflow with GitHub:

  1. Create feature branch locally
  2. Push to GitHub: git push origin feature-branch
  3. Create Pull Request in GitHub
  4. Review and approve
  5. Merge in GitHub
  6. Webhook triggers Cloud deployment

Handling Merge Conflicts

Conflict Resolution

Critical Limitation

Note that Magento doesn't handle merge conflicts, so these must be resolved on your local git instance.

Conflict Resolution Workflow

  1. Pull both branches locally: 
    git fetch --all
git checkout master
git pull
git checkout feature-branch
git pull
  2. Attempt merge locally: 
    git checkout master
git merge feature-branch
  3. If conflicts occur:
    • Git shows conflicted files
    • Open files and resolve conflicts manually
    • Look for <<<<<<<, =======, >>>>>>> markers
    • Edit to desired final state
  4. Complete merge: 
    git add .
git commit -m "Resolve merge conflicts"
git push origin master
  5. Cloud receives clean merge:
    • Webhook triggers deployment
    • No conflicts on Cloud side

Best Practices

Synchronization and Merge Guidelines

Do's

  • Sync staging from production regularly: Keep environments aligned
  • Test after sync: Verify functionality works
  • Merge in primary git repo: Use GitHub/GitLab for merges
  • Resolve conflicts locally: Don't rely on Cloud
  • Document sync schedule: Regular data refreshes
  • Backup before sync: Create snapshot before overwriting
  • Use CLI for automation: Script repetitive syncs

Don'ts

  • Don't sync without backup: Database will be overwritten
  • Don't use Cloud merge with external git: Merge in GitHub/GitLab instead
  • Don't forget webhook setup: Ensure GitHub triggers Cloud
  • Don't ignore conflicts: Resolve properly
  • Don't sync production from staging: Wrong direction!

Common Scenarios

Real-World Examples

Scenario 1: Refresh Staging with Production Data

Use Case:

Need to test with real production data in staging.

Solution:
# Sync staging from production (or master on Starter)
magento-cloud environment:checkout staging
magento-cloud environment:synchronize

# Test with production data
# Fix any issues
# Deploy to production when ready

Scenario 2: Deploy Feature to Production

Use Case:

Feature tested in integration, ready for production.

Workflow:
  1. Merge feature to master in GitHub
  2. Create Pull Request
  3. Review and approve
  4. Merge in GitHub
  5. Webhook triggers Cloud production deploy
  6. Verify deployment success

Exam Tips

Key Points to Remember

  • Sync definition: Loads database and code from parent branch
  • No git hierarchy: Master on same plane as other branches
  • Cloud adds hierarchy: Three-dimensional parent-child perspective
  • Starter hierarchy: Master > Staging > Integration
  • Pro hierarchy: Master (branch), Production (serving), Staging > Integration > branches
  • Sync tools: Project Web Interface or Magento Cloud CLI
  • Cloud is upstream: When using GitHub/GitLab/BitBucket
  • Code sync = git pull: Essentially git pull origin master
  • Merge in primary repo: Don't use Cloud merge with external git
  • Practical experience: Sync staging data from master
  • Merge function: Merges child branch code to current branch
  • Starter promotion: Merge staging into master
  • Pro promotion: Merge staging into production
  • Merge locations: CLI, Web UI (no external git), or GitHub/GitLab
  • No conflict resolution: Magento doesn't handle conflicts - resolve locally
Previous: Cloud 8.04 Apply Patches Practice Cloud 8.05