Skip to content
Notifications
Clear all

Check out my 'migration runbook' template. It's just a checklist, but it saved us.

1 Posts
1 Users
0 Reactions
63 Views
(@crm_trailblazer_7)
Honorable Member
Joined: 7 months ago
Posts: 433
Topic starter   [#28618]

We migrated from Jenkins to GitLab CI last quarter. The marketing slides made it look like a three-day job. It was not.

Our actual migration took six weeks, with two of those spent untangling a permissions and secrets mess that wasn't in the vendor's "accelerator" guide. What got us through was a brutally simple runbook we built as a living checklist. It's not fancy, but it forced us to document every assumption.

Here's the core structure. The value is in the details you add to each line.

### Pre-Migration: Discovery & Inventory
* Catalog all existing pipelines (repo, Jenkinsfile location, trigger type)
* Document all external integrations (artifact repos, notification channels, deployment targets)
* **List every secret and its current management method.** This is the biggest pain point.
* Define mapping of old Jenkins agents/labels to new GitLab runners/tags
* Set a "migration complete" criteria (e.g., all prod deployments running on new system for 1 week)

### Execution: Pipeline Translation
* Start with low-risk, non-prod pipelines.
* Use a consistent template for the new `.gitlab-ci.yml` files. Example base:

```yaml
# GitLab CI Template - Runner tagging and stages
default:
tags:
- your-runner-tag

stages:
- build
- test
- deploy

variables:
ARTIFACT_PATH: "$CI_PROJECT_DIR/build"

# Include actual jobs from separate files for cleanliness
include:
- local: '/.gitlab/ci/build.yml'
- local: '/.gitlab/ci/test.yml'
```

* Validate secret injection works in the new system before cutting over any deployment job.
* Run old and new pipelines in parallel for at least one full cycle, comparing outputs/artifacts.

### Post-Cutover: Validation & Cleanup
* Decommission old pipelines in stages, not all at once.
* Audit runner utilization and costs.
* Revoke old secrets and access keys. This is often forgotten.
* Update all internal documentation links.

The checklist forced accountability. When the network team asked why their firewall rules were taking so long, we could point to line 14: "Infrastructure team to open VPN tunnel to staging environment by T-10 days." It was late. That blocked us. The data was in the runbook.

If you're planning a move, start with this skeleton and make it your own. The time you spend filling it out will save you from a dozen "we forgot about that" emergencies.


Show me the query.


   
Quote