Everyone talks about migration "runbooks" like they're sacred texts. They're not. They're just checklists you actually use.
Ours covered the real gotchas. Pre-flight: inventory every pipeline, secret, and external integration. Cutover: how to flip the webhooks, redirect the badges, handle the in-flight builds. Post-mortem: kill old access, verify cost savings, update the onboarding docs.
The whole thing was two pages. It saved us because it forced us to think about the order of operations *before* we were in the middle of it. The migration took three weekends, mostly because of weird custom plugins. The checklist didn't make it easy, it just made it predictable.
Trust but verify.
That phrase about "sacred texts" really hits home. I've been on the receiving end of those massive, polished runbooks that feel more like compliance documents than something you'd actually open during a panic at 2 AM. The value isn't in the document's weight, it's in the forced, structured conversation it creates beforehand.
I'm curious about the "inventory every pipeline, secret, and external integration" part of your pre-flight. In our manufacturing context, that always uncovers a forgotten EDI mapping or a custom script that some consultant wrote ten years ago and never documented. How did you handle verifying that inventory? Was it a matter of just running network logs, or did you have to dig through old config files in some obscure directory?
You mention weird custom plugins taking three weekends. That predictability, even when things are hard, is the entire win. Knowing you have a step for each potential failure point means you aren't also inventoring a process while the clock is ticking.
Exactly. We found that pure network logging missed the passive integrations, the ones that only wake up on a trigger. Our verification was a three step process, and it was mostly manual.
First, we used configuration scraping from our CI/CD system to list every job definition and its environment hooks. That caught the obvious ones. Second, we ran a series of controlled "quiet period" tests where we severed network egress and monitored for failed callbacks or scheduled jobs timing out. That's how we found the legacy webhook that triggered a parts ordering system every Friday at 5 PM. Finally, we did the archaeology you mentioned, grepping through shared volumes and home directories for scripts containing API endpoints or credential patterns. It was tedious.
Your manufacturing analogy is perfect. The "consultant script from ten years ago" is our equivalent of a custom plugin living in a forked repo that nobody owns. The checklist forced us to assign an owner to find each item, which was the real value. Without that, those items just get discussed and then forgotten until the migration breaks them.
> Without that, those items just get discussed and then forgotten
That's it exactly. The forced ownership is the only thing that works. We used the same "quiet period" trick but for Salesforce integrations. Shut off API access for a sandbox org and waited for the angry Slack messages. Found two reporting "dashboards" that were just hidden, scheduled data pulls. The archaeology phase is where you really earn your pay, though. Everyone thinks their house is clean until you have to move.
CRM is a necessary evil
You've nailed the core value: predictability over ease. The checklist format forces a brutal prioritization of dependencies.
Most teams skip the "kill old access" step in their post-mortem. They're exhausted and it's an easy win to defer. I've seen old service accounts with write access linger for years, creating a compliance nightmare. Documenting the decommission date and owner in the checklist stops that.
Your two page limit is key. Anything longer becomes another document you have to migrate.
Five nines? Prove it.