> ## 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 & Branches

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

export const ProductName = "The Morph Platform";

export const productName = "the Morph Platform";

{ProductName} 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, {productName} 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 icon="code-compare" /> 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, {productName} 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 (<Icon icon="code-compare" />). 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.
</Note>

***

## 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. {ProductName} creates the milestone branch from the feature branch
2. The agent commits all task work to this branch
3. On completion, {productName} 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, {productName} 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, {productName} 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>
  **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.
</Warning>

***

## 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

{ProductName} supports all major Git providers:

<CardGroup cols={3}>
  <Card title="GitHub" icon="github" href="/setup/github-integration">
    GitHub.com integration via GitHub App
  </Card>

  <Card title="GitLab" icon="gitlab" href="/setup/gitlab-integration">
    GitLab.com integration via OAuth
  </Card>

  <Card title="Azure DevOps" icon="microsoft" href="/setup/azure-devops-integration">
    Azure DevOps Services via Microsoft Entra ID
  </Card>
</CardGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="Reviewing Pull Requests" icon="code-pull-request" href="/migration/pull-requests">
    How to review and merge milestone PRs
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts#project">
    Project setup and branch strategy overview
  </Card>

  <Card title="Roadmap" icon="map" href="/migration/roadmap">
    How your migration is organized and tracked
  </Card>

  <Card title="Milestones & Tasks" icon="list-check" href="/migration/milestones-and-tasks">
    The milestone execution lifecycle
  </Card>
</CardGroup>