Skip to main content
uses a structured branching strategy to keep your migration organized, reviewable, and safe. Every code change happens on an isolated branch—nothing is merged to your mainline without your explicit approval.

​
Feature Branch

Every project has a feature branch that acts as the integration point for all migration work. This branch is shared across all target repositories in the project.
  • Default name: morph-main
  • Customizable: You can change the feature branch name during project creation if your organization has naming conventions (e.g., feature/modernization, migration/java-to-kotlin)
  • Scope: The same feature branch name is used for all target repositories in the project
The feature branch is where completed milestone work accumulates. Each milestone merges into this branch, building up the full migration incrementally.

​
Project Start Point

At project creation time, records the commit SHA of each repository’s origin branch. This SHA marks the project’s starting point and serves as the baseline for tracking what has changed in the upstream mainline since the project began. You can click the icon next to the repo name (on the top left of the project page) to see those changes.

​
Upstream Changes

As your team continues pushing changes to the repository’s mainline during the migration, makes it easy to stay aware of what’s changed. Viewing upstream changes: On the project page, below the project title, you can see a list of all project related repos with a diff icons (). Click it to see all upstream commits pushed to the repository’s mainline since the project started (i.e., since the recorded start SHA).

​
Upstream Sync

Between milestones, you can trigger an upstream sync to incorporate mainline changes into your migration. This is useful when significant upstream work has landed and you want the migration to stay aligned with the latest codebase state. When triggered, upstream sync will:
  1. Update the project’s starting SHA to the current mainline HEAD
  2. Create an ad-hoc sync milestone that follows the standard milestone procedure—including code review, functional testing, and PR creation
  3. Rebase any in-progress milestone branches so they incorporate the new baseline
  4. Adjust the plan for upcoming milestones to account for the upstream changes
The sync milestone goes through the same lifecycle as any other milestone: the agent executes the work, creates a PR, and you review and merge before continuing.
Upstream sync is not supported in projects that were created before this feature was introduced. Only projects created after upstream sync became available can use it.

​
Milestone Branches

Each milestone gets its own branch, branched off from the feature branch:
  • Naming format: <project_name>-milestone_<milestone_number>-<uuid>
  • Example: payments-api-migration-milestone_3-a1b2c3d4
This keeps each milestone’s work isolated until it passes review. The milestone lifecycle is:
  1. creates the milestone branch from the feature branch
  2. The agent commits all task work to this branch
  3. On completion, creates a PR from the milestone branch → feature branch
  4. You review and merge the PR
  5. Dependent milestones are unlocked; sibling milestone branches may receive a rebase if they share dependencies with the merged code
When milestones are independent (no shared file dependencies), multiple milestone branches can exist simultaneously. Each runs in isolation and produces its own PR. When one of them merges, checks whether remaining in-progress branches need to incorporate the new code. If so, it flags them as Rebase Required and the agent handles the integration automatically when you trigger it.

​
End-of-Project PR

When all milestones are complete and merged into the feature branch, creates a final Pull Request from the feature branch to the target branch:
  • Default target: The repository’s default branch (e.g., main, master)
  • Customizable: You can select a different target branch during project creation if needed
This final PR represents the entire migration in one reviewable unit. Your team can review it holistically, run CI/CD, and merge when ready.
Do not use a temporary branch as the project’s default branch. The selected branch serves as the base branch for the final PR and its tip commit is recorded as the project’s reference SHA. If this branch or commit is deleted, the project will be blocked and can only be recovered by restarting the project. Use a long-lived branch (e.g., main, master, develop) that will not be deleted during the migration.

​
Branch Flow Diagram

​
Supported Git Providers

supports all major Git providers:

GitHub

GitHub.com integration via GitHub App

GitLab

GitLab.com integration via OAuth

Azure DevOps

Azure DevOps Services via Microsoft Entra ID

​
Summary

Reviewing Pull Requests

How to review and merge milestone PRs

Core Concepts

Project setup and branch strategy overview

Roadmap

How your migration is organized and tracked

Milestones & Tasks

The milestone execution lifecycle