> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Strategy and Branches

> How Morph manages branches, commits, and pull requests across your repositories

The Morph Platform 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](/core-concepts#project) 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, the Morph Platform 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, the Morph Platform 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.

> [!NOTE]
>
> 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. The Morph Platform creates the milestone branch from the feature branch
2. The agent commits all task work to this branch
3. On completion, the Morph Platform creates a **PR from the milestone branch → feature branch**
4. You [review and merge](/migration/pull-requests) 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, the Morph Platform 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, the Morph Platform 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.

> [!WARNING]
>
> **Point your project at a branch that will still exist when the migration finishes.** The Morph Platform measures the whole migration against the branch you start from, and delivers the final pull request back into it. If that branch is deleted mid-project, the project cannot be recovered and has to be started again.
>
> Use a long-lived branch — `main`, `master`, `develop` — and not a temporary or release branch that may be cleaned up along the way.

***

## Branch Flow Diagram

```mermaid theme={null}
gitGraph
   commit id: "existing"
   commit id: "project start (SHA recorded)"
   branch morph-main
   commit id: "milestone 1 merge"
   branch milestone-2
   commit id: "milestone 2 work"
   checkout morph-main
   branch milestone-3
   commit id: "milestone 3 work (parallel)"
   checkout morph-main
   merge milestone-2 id: "milestone 2 merge"
   merge milestone-3 id: "milestone 3 merge (rebased)"
   checkout main
   commit id: "upstream changes"
   checkout morph-main
   commit id: "upstream sync milestone"
   commit id: "final milestone merge"
   checkout main
   merge morph-main id: "end-of-project PR"
```

***

## Supported Git Providers

The Morph Platform supports all major Git providers:

> **[GitHub](/setup/github-integration)**
>
> GitHub.com integration via GitHub App

> **[GitLab](/setup/gitlab-integration)**
>
> GitLab.com integration via OAuth

> **[Azure DevOps](/setup/azure-devops-integration)**
>
> Azure DevOps Services via Microsoft Entra ID

***

## Summary

| Concept | Details |
| - | - |
| Feature branch | `morph-main` (customizable at project creation) |
| Milestone branch | `<project_name>-milestone_<number>-<uuid>` |
| Milestone PR | Milestone branch → feature branch |
| End-of-project PR | Feature branch → target branch (default: repo default branch) |
| Start point | Commit SHA recorded at project creation |
| Upstream visibility | Diff icon on Roadmap shows mainline changes since start |
| Upstream sync | Updates start SHA, creates sync milestone, rebases affected branches |

***

## Related Docs

> **[Reviewing Pull Requests](/migration/pull-requests)**
>
> How to review and merge milestone PRs

> **[Core Concepts](/core-concepts#project)**
>
> Project setup and branch strategy overview

> **[Roadmap](/migration/roadmap)**
>
> How your migration is organized and tracked

> **[Milestones & Tasks](/migration/milestones)**
>
> The milestone execution lifecycle


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.