Migration and Recovery: Preserve History Before Changing It
Plan an Azure DevOps-to-GitHub migration, choose revert rather than destructive reset on shared history, and respond correctly to committed secrets.
Moving house is more than moving the furniture
Copying a repository’s Git objects is like moving the furniture. Permissions, build connections, work-item links, large files, and release automation are the utilities and address changes. A migration is incomplete if code arrives but nobody can build or trace it.
Choose the migration mechanism after inventorying what must survive. A Git mirror moves Git history and refs, not every platform object. GitHub Enterprise Importer supports a documented Azure DevOps migration path with its own prerequisites, supported data, and exclusions. Do not promise that every Boards item, pipeline setting, extension, policy, or secret migrates with the repository.
Plan before importing
| Inventory | Question to answer |
|---|---|
| Repository | Which branches, tags, sizes, and LFS objects exist? |
| Collaboration | Which PRs, identities, discussions, and links must remain usable? |
| Security | Who may migrate, administer, contribute, and bypass? |
| Automation | Which webhooks, service connections, runners, and pipelines need recreation? |
| Consumers | Which clones, submodules, package references, and integrations use the old URL? |
| Cutover | When is the source frozen and what is the rollback criterion? |
Use a test migration first. Keep tokens out of command history and logs; follow the current tool’s authentication guidance rather than embedding secrets into a remote URL.
For Azure DevOps-to-GitHub Enterprise Importer, verify the current licensing, organization prerequisites, supported destination, and source access. Git LFS objects are not included in the documented importer migration; plan their separate transfer and verification. A small successful Git checkout does not prove large assets arrived.
Verify the destination as a working system
After the test import, compare branch heads and tags, inspect representative history and PR links, fetch LFS content where used, and run the actual build from a clean clone. Recreate required branch policies/rulesets deliberately; do not assume source controls become equivalent destination controls automatically.
Test one integration end to end: open a draft PR, run checks, inspect work tracking, and confirm the intended reviewer and access restrictions. Verify that old service credentials are not accidentally retained or exposed. Keep the old source read-only during a controlled observation period if the migration plan calls for it.
Do not delete the source merely because the importer reports success. A tool-completed operation is one part of acceptance, not the entire cutover decision.
Choose recovery by what must be preserved
| Situation | Usually appropriate starting point | Main caution |
|---|---|---|
| Bad commit already shared | git revert | Creates a new inverse commit; conflicts and tests still matter |
| One file needs its older content | Restore that path from a known commit, then review and commit | Can overwrite local work on that path |
| Local branch pointer moved unexpectedly | Inspect git reflog and create a recovery branch | Reflogs are local and not indefinite backups |
| Secret committed | Revoke/rotate first, then coordinate history cleanup | Deleting the visible file does not revoke the credential |
Use these read-oriented commands to inspect a disposable repository:
git status --short
git log --oneline -5
git show HEAD
git reflog -5If a non-merge shared commit introduced a bug, a revert records a new change rather than erasing other contributors’ history:
git revert <BAD-COMMIT>Replace the placeholder only after inspecting the exact commit and ensuring the working tree is ready. Merge commits require an explicitly chosen mainline and additional reasoning; do not treat them as interchangeable with ordinary commits.
reset --hard and force-pushing can destroy uncommitted changes or rewrite history others depend on. They are not routine first responses to a shared mistake. An assistant should explain the effect before proposing them.
A leaked secret is an incident, not just a Git task
Revocation or rotation removes the credential’s usefulness. History rewriting removes selected content from reachable history under a coordinated procedure. Both may be needed, but one does not replace the other.
Check forks, clones, logs, artifacts, and cached references within your incident process. Avoid placing the real secret into a search command that will itself be logged. Use supported secret-scanning tools and identifiers. Coordinate rewritten history with collaborators and the hosting provider’s documented sensitive-data removal process.
A usable production token was committed and then deleted in a later commit. What is the first priority?
Try it: rehearse a reversible recovery
Prerequisites: Git and a new local disposable repository. Use harmless text only; never create a real secret for this exercise.
- Commit a text file, then commit an intentionally incorrect sentence.
- Inspect both commits and revert the second one.
- Confirm the corrected content and the three-step history: original, mistake, inverse.
- Write a migration acceptance checklist covering Git refs, large assets, access, CI, and one integration.
Expected observation: the revert preserves the original history and adds an auditable correction. Your checklist distinguishes Git transfer from platform cutover.
Cleanup: remove only your disposable exercise repository using your normal safe cleanup process. No hosted migration or production credential mutation is required by this exercise.
Decision check: the import succeeded but a build fails
Compare the build’s dependencies, secrets, runner access, LFS assets, and old URL references before blaming the imported source. Migration acceptance requires a usable delivery path.