Skip to content

Discover What Vertex Can Build for Your Business

DevOps3 min read

How to hand over a codebase properly

A handover isn't a repository transfer and a farewell call. What a receiving team actually needs to be productive on the first Monday — and the one test that proves they are.

The test of a handover isn't whether the new team can read the code. It's whether they can ship a one-line change on their own, on the first Monday.

On This Page

Handover usually gets scheduled as a meeting. Repository access is granted, a walkthrough is recorded, somebody says “ping us if anything comes up,” and the engagement closes. Three weeks later the receiving team discovers a certificate renewing through an account nobody transferred, and the goodwill from an otherwise good project evaporates in an afternoon. A handover isn't a transfer of files. It's a transfer of the ability to operate a system, and it either works on the first Monday or it didn't happen.

One test, run for real

The only handover check worth anything is behavioural: can someone on the receiving team, unaided, change one line of copy and get it into production? Not describe how — actually do it. That single task exercises almost everything that matters. Repository access, a working local environment, dependency installation, the test suite, the review process, credentials, the deploy pipeline, and whatever manual step nobody thought to write down because they had done it two hundred times and it stopped registering as a step years ago.

Run it while the outgoing team is still engaged and still paid, and every gap surfaces as a question someone can answer in five minutes rather than an archaeology project six weeks later. If it can't be done on day one, the handover isn't finished, however complete the documentation looks.

The documentation that actually gets read

Comprehensive documentation is mostly a way of feeling responsible. Long architecture documents get skimmed once and then rot, because nothing forces them to stay true. What receiving teams use is short and operational: how to run it locally, how to deploy, how to roll back, what to do when each specific alert fires, and where the environment variables come from. That's a handful of pages, it gets verified by the test above, and every line of it fails visibly the moment it goes stale.

The one long-form document worth writing is different in kind: a record of decisions and the reasons behind them. Why this database, why the queue sits where it does, what was tried and abandoned, which constraint forced the odd-looking part in the middle of the domain model. New teams don't need the system described — they can read it. They need to know which strange choices are load-bearing and which are merely old. Without that, the first instinct is to tidy something that was deliberate, and the second is an incident.

Everything shaped like a key

The most common failure isn't code at all, it's the accounts around it. Domain registrar, DNS, TLS certificates, the app-store publisher account, cloud billing ownership, error tracking, analytics, the mail provider, the payment gateway dashboard, the API keys sitting in a CI configuration nobody has opened since it was written. A surprising share of these are typically in one person's name, sometimes with two-factor tied to a phone that is leaving with them.

So we write down every external service the product touches: who owns it, what it costs, when it renews, and how the new team takes it over. Then we transfer it before the final week, and verify access from the receiving side rather than the sending side. An inventory nobody has tested is just a list of future outages with dates already attached.

Do it alongside, not at the end

The best handovers don't have a handover phase. The receiving team is in the codebase weeks before the transition, taking real tickets while the people who wrote it are still around to review them, because that is the only mechanism that moves the knowledge which never makes it into writing. Pairing on a genuine bug transmits more than any document — it exposes how the system is reasoned about, not merely how it is arranged.

Where that isn't possible, the fallback is a shadow period: the outgoing team stops merging its own work and instead reviews the incoming team's for a fortnight. It feels inefficient, and it is the difference between a system that keeps being changed and one that quietly stops being changed — which is how most inherited software actually dies. Not in an outage, but in the slow, unrecorded decision to work around it rather than in it.

Share

Get More Practical Insights.

Receive new articles and guides on AI, software, operations, and digital growth.

Let’s build what’s next

Ready to Build a Smarter Future for Your Business?

Whether you’re launching a new product, modernizing systems, automating operations, or exploring AI, Vertex can help turn your next idea into a practical, scalable solution.