Repositories are tangible. They can be listed, sized, cloned and checked.
That makes them the natural centre of a migration plan—and the source of false confidence.
An enterprise DevOps migration becomes difficult at the edges around the repository:
- the pipeline that relies on an old extension;
- the service connection whose owner left the company;
- the agent with undocumented network access;
- the work-item link expected by audit;
- the release approval performed outside the platform;
- the binary files that make distributed source control painful;
- the dashboard whose meaning depends on an old area-path hierarchy;
- the production deployment that only succeeds when a specific person runs it.
A credible playbook must migrate the delivery capability, preserve required evidence and support the people who will operate the target system.
Phase 0: Mobilise around outcomes and authority
Before discovery, establish the programme boundary.
Confirm:
- accountable executive sponsor;
- platform owner;
- migration decision authority;
- security, audit and records-management representatives;
- product and engineering representation;
- target outcomes and measures;
- platforms and organisations in scope;
- data classifications and residency constraints;
- freeze, rollback and decommission authority;
- communication and escalation paths.
Create a migration control record containing facts, assumptions, decisions, risks, dependencies and unresolved questions. Keep it current.
Exit criteria
- outcomes are agreed;
- decision rights are explicit;
- source and target boundaries are named;
- success measures have baselines or an agreed plan to obtain them.
Phase 1: Discover the estate
Use platform APIs and scripts to create the inventory, but validate it with teams. Automated discovery finds objects. People explain why those objects matter.
Repository discovery
Capture:
- version-control type: TFVC or Git;
- size, history and large files;
- active and stale branches;
- submodules and cross-repository dependencies;
- branch policies;
- pull-request state;
- hooks and integrations;
- sensitive information and committed credentials;
- ownership and business criticality.
Work-management discovery
Capture:
- organisation, collection, project and team structure;
- process templates and custom fields;
- area and iteration paths;
- work-item types and volumes;
- queries, dashboards and reporting dependencies;
- links between work items, commits, builds, releases and tests;
- personal assets that need deliberate handling.
Pipeline discovery
Capture:
- classic, YAML and scripted definitions;
- shared templates;
- custom tasks and marketplace extensions;
- agents, pools, runners and capabilities;
- service connections and authentication;
- variable groups, secure files and secrets;
- package feeds and artefact stores;
- environments, approvals and gates;
- deployment targets and network routes;
- failure rate, duration and actual use.
Security and governance discovery
Capture:
- identity provider and tenant;
- users, groups, administrators and external collaborators;
- permission model and privileged access;
- repository policies;
- scanning and evidence requirements;
- data-retention obligations;
- separation-of-duties controls;
- exception processes;
- audit integrations.
Operational discovery
Capture:
- platform support ownership;
- incident and request paths;
- backup or archival assumptions;
- monitoring and capacity constraints;
- change windows;
- business continuity requirements;
- undocumented manual recovery processes.
Dependency classification
Classify each asset:
- migrate as-is where supported and justified;
- transform into the target pattern;
- rebuild because automation or fidelity is unavailable;
- integrate temporarily during transition;
- archive for history or evidence;
- retire because there is no continuing need;
- block pending a material decision or dependency.
Exit criteria
- inventory coverage is accepted by platform and product owners;
- dependencies and owners are mapped;
- assets are classified;
- unknowns that could change the target design are visible.
Phase 2: Design the target platform and migration factory
Do not move production teams into a target that is still being invented.
Design the target topology
Define:
- enterprise, organisation and project structure;
- repository naming and ownership;
- team and permission model;
- identity lifecycle;
- network access;
- agent or runner architecture;
- package and artefact strategy;
- environment representation;
- work-management system of record;
- integration boundaries;
- audit and retention model.
Establish guardrails
Create minimum standards for:
- repository creation;
- branch protection;
- pull-request review;
- secret handling;
- dependency and code scanning;
- pipeline provenance;
- reusable workflows;
- deployment approvals;
- production access;
- logging and evidence;
- exceptions.
Guardrails should be automated where practical. Document the reason behind each one.
Build golden paths
Provide tested starter patterns for common workloads, such as:
- web application;
- API or microservice;
- data workload;
- infrastructure-as-code repository;
- containerised workload;
- legacy application deployed through a private runner or agent.
Each pattern should include repository structure, CI, security controls, artefact publishing, environment promotion, observability hooks and ownership metadata.
Build the migration factory
The factory is the repeatable combination of:
- discovery scripts;
- readiness scoring;
- migration tooling;
- transformation rules;
- validation automation;
- runbooks;
- communication templates;
- rollback procedures;
- exception handling;
- evidence capture;
- wave reporting.
Automate the repeatable steps, but keep decisions visible. A script can detect a classic pipeline; it cannot decide whether that pipeline should be converted, retired or temporarily retained.
Exit criteria
- target architecture is approved;
- identity, runners/agents and core policies work;
- representative golden paths are usable;
- migration and rollback runbooks exist;
- validation evidence is defined.
Phase 3: Clean before moving
Source clean-up reduces cost and failure risk.
Ask teams to:
- remove stale branches where policy allows;
- remove or relocate binaries unsuitable for Git;
- close or deliberately handle open pull requests;
- identify active repositories;
- rotate exposed or unknown credentials;
- remove unused extensions and integrations;
- convert personal assets into shared assets where justified;
- document service owners;
- identify pipelines that no longer run;
- confirm retention requirements.
For TFVC-to-Git migrations, make explicit decisions about:
- repository boundaries;
- branch mapping;
- how much history to migrate;
- treatment of large files;
- author identity mapping;
- changeset-to-commit validation;
- whether the old system remains available as an archive.
Full history is not automatically the best technical choice. A current snapshot plus a controlled historical archive may serve the business better for very large or complex TFVC estates. The choice must be approved against engineering, audit and legal needs.
Exit criteria
- each pilot asset has an owner;
- clean-up actions are complete;
- retention and history decisions are recorded;
- credentials and production dependencies are understood.
Phase 4: Run representative pilots
Use at least two pilot waves:
- a controlled technical pilot to prove the factory;
- a representative business pilot to prove the operating model.
Rehearse the full sequence
- take the agreed source snapshot;
- apply readiness checks;
- migrate or convert repository content;
- recreate or transform policies;
- migrate or rewrite pipelines;
- configure identities, secrets and service connections;
- validate packages and artefacts;
- deploy into non-production;
- run functional, security and operational tests;
- validate traceability and evidence;
- rehearse cutover and rollback;
- obtain product-owner and control-owner acceptance.
Validate more than file counts
Repository validation:
- expected default branch;
- commit or changeset sampling;
- tags and relevant branches;
- author mapping;
- large-file handling;
- repository policies;
- pull-request behaviour.
Pipeline validation:
- triggers;
- variables and secrets;
- build outputs;
- test results;
- artefact integrity;
- deployment permissions;
- environment promotion;
- approvals and evidence;
- retry and rollback behaviour.
Operational validation:
- monitoring and alerts;
- support access;
- incident runbooks;
- capacity and concurrency;
- private network access;
- ownership and escalation.
User validation:
- everyday developer flow;
- product traceability;
- support-team administration;
- security finding triage;
- onboarding instructions.
Exit criteria
- pilot acceptance is recorded;
- defects and manual steps are measured;
- the factory and target standards are updated;
- wave estimates use pilot evidence rather than early assumptions.
Phase 5: Plan migration waves
Group products by more than technical similarity.
Use:
- business criticality;
- technical complexity;
- regulatory sensitivity;
- team readiness;
- shared dependencies;
- change-calendar constraints;
- migration-factory fit;
- support capacity.
A wave should be small enough to support, but large enough to reveal shared-system issues.
Readiness gate
Before a team enters a wave, confirm:
- product and technical owners;
- approved migration classification;
- source clean-up;
- user and service identity mapping;
- pipeline and integration plan;
- test plan;
- cutover window;
- rollback trigger;
- communication recipients;
- hypercare availability;
- sign-off responsibilities.
Red status must mean “not ready,” not “proceed and hope.”
Phase 6: Cut over with controlled deltas
A common migration pattern includes:
- advance communication;
- initial bulk migration or rehearsal;
- reconciliation and remediation;
- source freeze or read-only mode;
- final delta;
- target validation;
- go/no-go decision;
- user redirection;
- hypercare;
- rollback if agreed thresholds are breached.
The exact sequence depends on the tooling and asset type.
Define go/no-go thresholds
Examples:
- all critical repositories validated;
- all production pipelines pass their agreed tests;
- no unresolved critical security finding introduced by the move;
- required audit links or archive access confirmed;
- service identities and production permissions validated;
- support coverage active;
- rollback remains viable.
Avoid the vague criterion “migration completed successfully.”
Protect the source
Once the final delta begins, uncontrolled source changes create divergence. Apply the agreed freeze or read-only control and communicate its meaning.
Do not delete the source during cutover. Retention and decommissioning are separate, governed activities.
Phase 7: Stabilise and measure
Hypercare should be designed before cutover.
Track:
- failed builds and deployments;
- permission and identity issues;
- missing dependencies;
- user support requests;
- pipeline duration and concurrency;
- security finding flow;
- defect escape;
- unresolved manual remediation;
- adoption of standard workflows.
Hold short, evidence-based reviews after every wave:
- What failed?
- What almost failed?
- What manual step should be automated?
- Which assumption was wrong?
- Which training gap appeared?
- Which target standard caused unnecessary friction?
- What must change before the next wave?
Update the migration factory continuously.
Phase 8: Archive and decommission deliberately
Decommissioning requires its own gate.
Confirm:
- all in-scope teams have accepted the target;
- required history is accessible;
- audit and retention evidence is approved;
- backups or exports have been tested where required;
- integrations no longer depend on the source;
- users and service accounts are removed or disabled appropriately;
- licences and infrastructure can be terminated;
- ownership of the archive is assigned;
- retrieval and eventual disposal processes are documented.
An old platform left running “just in case” becomes an unmanaged security and cost liability. An old platform removed too quickly can destroy evidence and operational knowledge.
Archive with purpose; decommission with authority.
Workstream checklist
| Workstream | Key deliverables | |---|---| | Programme and governance | Outcomes, RACI, decision log, risk register, wave plan | | Architecture | Current-state map, target topology, integration and responsibility views | | Repositories | Inventory, clean-up, conversion rules, validation report | | Work management | Mapping, process decisions, traceability and archive approach | | CI/CD | Pipeline classification, reusable patterns, conversion and test evidence | | Identity and security | Access model, secrets plan, policies, scanning and exceptions | | Agents/runners and network | Capacity model, connectivity, hardening and support | | Data and history | Fidelity requirements, retention classes, archive and retrieval | | Adoption | Communications, training, champions, office hours and feedback | | Operations | Monitoring, incident process, support model, hypercare and handover | | Commercial | Licensing, transition overlap, infrastructure and support costs |
Common failure modes and corrections
Failure: repository counts drive the schedule
Correction: Size waves using dependency and pipeline complexity, business criticality and team readiness.
Failure: every asset is migrated unchanged
Correction: Classify assets into migrate, transform, rebuild, integrate, archive or retire.
Failure: pipeline conversion is treated as syntax translation
Correction: Validate behaviour, identities, artefacts, environments, approvals, evidence and failure handling.
Failure: history is discussed only after a tool drops metadata
Correction: Define history consumers and fidelity requirements before tool selection.
Failure: security controls are enabled without operating processes
Correction: Assign finding ownership, severity rules, remediation expectations and exception governance.
Failure: the easiest repository becomes the only pilot
Correction: Pilot representative complexity without starting with the most critical workload.
Failure: training happens at cutover
Correction: Involve users in pilots, provide role-based learning and keep support available through early production use.
Failure: the source remains indefinitely
Correction: Establish archive ownership, retention gates and a funded decommission plan from the start.
A compact go/no-go scorecard
Score each area green, amber or red:
| Area | Green means | |---|---| | Business readiness | Owner, window and impact accepted | | Repository readiness | Cleaned, classified and validated in rehearsal | | Pipeline readiness | Target behaviour tested end to end | | Identity readiness | User and workload access verified | | Security readiness | Controls, evidence and exceptions approved | | Data/history readiness | Fidelity and archive requirements satisfied | | Operational readiness | Monitoring, support and rollback active | | Adoption readiness | Users trained and communication complete |
Any red item needs a named decision: remediate, rescope, defer or explicitly accept the risk through the authorised governance path.
The playbook is a learning system
No enterprise migration plan survives first contact unchanged.
The answer is not less planning. It is a plan designed to learn:
- discover systematically;
- make assumptions visible;
- test representative cases;
- automate repeated work;
- measure what happens;
- improve between waves;
- retain human decision gates where consequences matter.
That is how a repository migration becomes a sustainable software-delivery transformation.
How CloudNala can help
CloudNala structures migration as a repeatable, evidence-led factory with explicit architecture and governance gates. The objective is not only to complete a cutover. It is to leave the organisation with a simpler platform, reusable delivery paths, clearer ownership and an operating model that improves after the migration team has left.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Plan Your DevOps Migration or write to us at consult@cloudnala.co.za