Preserving Work‑in‑Progress From Forks During Migration to GitHub.com

Preserving Work‑in‑Progress From Forks During Migration to GitHub.com.md

📄 Preserving Work‑in‑Progress From Forks During Migration to GitHub.com

Overview

When migrating repositories from GitHub Enterprise Server (GHES) to GitHub.com, fork relationships are not preserved. As a result, any work‑in‑progress branches that exist only in forks will not automatically transfer. This document provides a step‑by‑step manual workflow to identify active branches in forks, bring them into the upstream repository, and ensure all relevant work is preserved before migration. The process works for:

• Individual developer forks
• Team‑maintained forks
• Long‑running feature branches
• Stale but important historical branches

---

1. Identify Forks and Active Branches

1.1 List all forks of the upstream repository

On GHES, navigate to the upstream repository:
Repository → Insights → Network
This view shows:

• All forks
• Branch activity
• Divergence from upstream

Alternatively, use the API:

curl -H "Authorization: token <TOKEN>" \
  https://<GHES_HOST>/api/v3/repos/<ORG>/<REPO>/forks

1.2 Identify branches that are ahead of upstream

For each fork:

git fetch https://<GHES_HOST>/<USER>/<FORK>.git
git branch -r

Then compare each branch to upstream:

git log upstream/main..origin/<branch>

If commits appear, the branch contains work not present in upstream.

---

2. Prepare a Local Workspace

2.1 Clone the upstream repository

git clone https://<GHES_HOST>/<ORG>/<REPO>.git
cd <REPO>

2.2 Add remotes for each fork

For each fork:

git remote add fork-<username> https://<GHES_HOST>/<USER>/<FORK>.git
git fetch fork-<username>

---

3. Bring Fork Branches Into the Upstream Repository

There are two recommended approaches depending on your preference for history.

---

Option A — Preserve Full History (Recommended)

3.1 Create a new branch in upstream using the fork branch

git checkout -b wip/<username>/<branch> fork-<username>/<branch>

3.2 Push the branch to the upstream repo

git push origin wip/<username>/<branch>

This preserves:

• Commit history
• Author information
• Merge context

---

Option B — Squash or Clean Up Before Migration

If you want a cleaner history:

3.1 Create a new branch

git checkout -b wip/<username>/<branch> fork-<username>/<branch>

3.2 Squash or rewrite history (optional)

git rebase -i upstream/main

3.3 Push the cleaned branch

git push origin wip/<username>/<branch>

---

4. Validate All Work Is Captured

4.1 Compare upstream and fork branches

git log upstream/main..origin/wip/<username>/<branch>

4.2 Confirm no unmerged commits remain

For each fork branch:

git log fork-<username>/<branch>..origin/wip/<username>/<branch>

If no commits appear, the branch is fully preserved.

---

5. Proceed With Migration to GitHub.com

Once all WIP branches are pushed into the upstream repository:

• The migration tool (GitHub Enterprise Importer, GitHub CLI, or API‑based migration) will include these branches.
• Developers will no longer rely on fork relationships.
• All active work is now centralized in the upstream repo.

---

6. Post‑Migration Cleanup (Optional)

After the repository is live on GitHub.com:

6.1 Recreate forks if needed

Developers can fork the migrated repository again.

6.2 Re‑establish branch protections

Apply policies to the new wip/* branches if required.

6.3 Convert WIP branches into PRs

Encourage developers to open pull requests from the preserved branches into main or other targets.

---

7. Summary

This workflow ensures:

• No work‑in‑progress is lost
• All fork‑based development is captured
• Migration to GitHub.com is clean and complete
• Developers retain their work without needing fork relationships It’s a simple, reliable, and repeatable process that works for organizations of any size.