01 · Workspace setup
Define the organizational boundary.
A workspace contains repository connections, assessments, Migration Packs, team ownership, integration settings, retention controls, and audit events. Assign workspace administrators before adding source-control access.
Recommended rolesUse administrators for identity, security, and integration controls; migration leads for assessment and execution; contributors for owned work; and viewers for reporting.
Workspace checklist
- Confirm organization and workspace name
- Assign administrators and migration leads
- Choose source-retention behavior
- Configure identity and role mappings
- Record audit-log and deletion requirements
02 · Connect repositories
Authorize the smallest useful scope.
Install or authorize the source-control connection, select organizations, and grant access only to repositories included in migration discovery. Analysis uses read-only source access by default.
- 1
Create the connectionChoose GitHub or GitLab and authenticate with an authorized organizational account.
- 2
Select repositoriesGrant access to applications, services, shared packages, infrastructure, and delivery repositories within scope.
- 3
Verify branch accessConfirm the production branch and any active migration branch required for comparison.
- 4
Review permissionsKeep source read only. Authorize issue creation separately if migration-task synchronization is required.
03 · Create assessment
Define a reproducible migration question.
Select a Migration Pack, source state, target technology or version, repositories, branches, and relevant production environments. CutoverGrid pins the assessment to source commits before analysis begins.
- Migration Pack
- The versioned rule system for the defined technical transition.
- Source state
- The current runtime, framework, database, delivery, or architecture state.
- Target state
- The technology or version the migration must reach.
- Scope
- Repositories, services, shared packages, infrastructure, environments, and owners included in analysis.
- Snapshot
- The exact commit identifiers used to make results reproducible.
04 · Evidence
Trace every finding to its source.
Findings preserve the Migration Pack version, analysis rule, dependency or configuration state, repository, commit, path, line where available, affected system, severity, and confidence.
Rule→Version→Repository→Commit→Path→Impact→Task→Gate
Confidence labels
High indicates direct, reproducible evidence. Medium combines direct evidence with a bounded inference. Low signals incomplete evidence. Manual review identifies a decision that needs accountable human confirmation.
05 · Readiness
Interpret readiness by dimension.
The overall score summarizes migration conditions; the dimension scores explain where work remains. Review dependency compatibility, application code, tests, infrastructure, operations, ownership, documentation, and rollback preparation separately.
Do not treat readiness as approval.A score communicates assessed conditions. Production cutover still requires the named technical gates and accountable approvals defined for the migration.
06 · Effort and confidence
Use ranges to make capacity decisions.
Effort estimates include a low and high bound, documented assumptions, exclusions, unresolved unknowns, relevant dependencies, and confidence. Resolve high-impact unknowns before committing to a narrow delivery window.
Range24–32engineer-days
ConfidenceMedium–high91% evidence coverage
Unknowns7manual review items
07 · Migration waves
Sequence work by dependency and risk.
Migration waves group owned tasks around prerequisites and system impact. Every task can carry evidence, an owner, estimated effort, acceptance criteria, validation steps, and rollback conditions.
- Establish the safety baseline
- Prepare the toolchain
- Upgrade shared packages
- Migrate low-risk services
- Migrate critical services
- Complete production cutover
- Remove transition controls
08 · Cutover gates
Require evidence before traffic moves.
Cutover gates express the technical and operational conditions that must be met. Typical gates cover build, unit tests, integration tests, contracts, performance, error rate, monitoring, rollback, and approvals.
✓ Passed — evidence meets the threshold! At risk — evidence is near or outside the threshold× Blocked — a required condition is not met○ Pending — evidence or approval is not complete
09 · Continuous rescanning
Keep the assessment aligned with repository change.
Run a rescan after relevant pull requests merge, shared packages release, CI changes land, or validation evidence updates. CutoverGrid compares the new snapshot, resolves findings with supporting evidence, adds newly introduced risks, and recalculates readiness.
10 · Exports and synchronization
Move execution into team workflows without losing context.
Publish findings and migration tasks to GitHub Issues, GitLab Issues, Jira, or Linear. Preserve the CutoverGrid evidence reference, acceptance criteria, owner, wave, dependencies, and validation gate in each synchronized record.