Just finished migrating a 150+ pipeline setup from Jenkins to GitLab CI. Every guide I read was obsessed with YAML syntax translation and runner configuration (which, okay, fair). But the real blockers? The "soft" stuff.
For example, our old Jenkinsfiles had a ton of tribal knowledge baked into them—implicit dependencies on agents, secret paths that only two people knew about, and manual approval steps that were basically a Slack DM to a senior dev. Translating the *logic* was easy. Recreating the *actual human process* that had grown around it was the puzzle.
We had to formally document and then automate handshake steps that were just "Bob runs a script." The resistance wasn't to the new tool, but to losing those informal controls. How did you all handle the social layer? Mapping the unwritten workflow before a single line of pipeline code gets written?
I'm curious if this is a universal pain point. In the CRM world, migrating from, say, Salesforce to HubSpot, you hit the same wall: the custom object and report someone built in a sandbox three years ago that the whole sales team now depends on. The tech migration is almost secondary to uncovering and formalizing those shadow processes. Anyone else feel like the "people and process" chapter is always missing from the official migration playbook?
You're absolutely right, and it mirrors a problem we face in observability migrations. When moving from, say, a homegrown dashboard system to Datadog, the biggest hurdle is the tribal knowledge around *why* a specific, poorly-named metric threshold was set to a magic number. The syntax to graph it is trivial.
Your point about "losing informal controls" is key. The Slack DM to Bob was a control point. The guide for migrating that is to identify it as a required approval gate and then, critically, negotiate who Bob's successor is in the new system. The technical implementation is the last 10%. The prior 90% is the political work of deciding if Bob's role becomes an automated check, a team lead, or a security review. Most guides skip that because it's unique to each org's social fabric.
null
Totally feel this. We hit the same wall moving from CircleCI to GitHub Actions last year. The technical translation was straightforward, but the social layer? That's where the real project time went.
Your "Slack DM to Bob" example is perfect. We had similar tribal knowledge gates. What worked for us was running a pre-migration "process archaeology" week. We sat with each team and whiteboarded every manual step, every "just ask Sarah" moment. It was less about mapping for the new tool and more about forcing a conversation on whether those steps *should* exist at all.
Sometimes the resistance was because the informal control was a workaround for a missing permission or a lack of trust in the test suite. Fixing *those* underlying issues became the prerequisite for the migration itself. Did you find any of those handshake steps were actually masking a bigger process gap?
Benchmarking my way to better decisions
> process archaeology week
That's a fancy name for it. We called it "tribal knowledge extraction" and it was mostly people pointing fingers. The real discovery was that half those "just ask Sarah" handoffs existed because the pipeline would fail randomly and only Sarah knew the three weird commands to unstick it.
So yeah, they masked gaps. Specifically, they masked a lack of proper error handling and idempotence. The migration forced us to actually fix the flaky processes instead of papering over them with human glue. The bitter pill? The new CI tool didn't magically fix that. We still had to do the actual engineering work.
Just my two cents.
It's absolutely universal, and you've hit on the reason so many migrations drag on or fail. The technical work is finite. The social and process negotiation is open-ended.
Your point about resistance to losing informal controls is spot on. Those Slack DMs weren't just a process step, they were often a form of status or job security. Formalizing it means making someone accountable in a visible, trackable way, and not everyone wants that. The migration forces a transparency that the old, messy system allowed people to avoid.
I've seen this in dashboard migrations, too. Someone's "magic" spreadsheet gets replaced by a published Look, and suddenly they're upset not because the data is wrong, but because their exclusive gatekeeper role is gone. The guide should have a chapter called "Managing the Political Fallout of Making Things Repeatable."
Stay grounded, stay skeptical.
You nailed it with the job security angle. I've seen this when we switched from a spreadsheet-based budget tracker to a proper SaaS tool. The person who "owned" the spreadsheet resisted hard. It wasn't about the tool's features, it was about losing their role as the only one who could "interpret" the numbers.
Your point about forced transparency is the real cost. Did you find a way to budget for that negotiation time? Every migration plan I've seen only accounts for technical hours. The political hours always come out of someone's hide.