Changing vendors, absorbing a contractor's work in-house, or inheriting software through an acquisition all present the same problem, and it is rarely the one people brace for. The code is usually comprehensible. What stops the incoming team is that the running system depends on small pieces of custody (an account, a key, a certificate, a DNS record, a build agent) that live outside the repository and were never written down. A handover that transfers only source code hands over an artifact, not a system.
What has to transfer beyond the repository
Treat the handover as an inventory of custody rather than a code drop. For every item, you need three facts: who holds it today, what the credential or transfer mechanism is, and whether the system stops working if it is not moved. The last one is what sets the order of operations, because some of these items cannot be recovered at all once the relationship with the outgoing team ends.
| Asset | Who typically holds it | Why it blocks you |
|---|---|---|
| Source repository and full history | The outgoing vendor's organization account | A zip export loses the commit history you need to date decisions; ask for the repository transferred |
| Cloud provider accounts and billing ownership | The vendor's account, often with your workload inside their tenant | Inside their tenant you cannot rotate credentials, change limits, or stop them turning it off |
| Domain registrar and DNS | Whoever bought the domain, sometimes a former employee | Without it you cannot move hosting, issue certificates, or repoint mail; recovery can take weeks |
| TLS certificates and their renewal mechanism | The vendor's automation or a manual calendar reminder | A renewal that silently ran on the vendor's server is a dated outage |
| Environment variables and secrets | A secrets manager, a CI configuration, or a local .env file | The application will build and still not run, and the missing values cannot be guessed |
| Third-party API keys and vendor accounts | Payment, email and SMS, mapping, error tracking, analytics | Some are registered to the vendor or a personal email and need their own transfer or reissue path |
| App store and distribution accounts | The vendor's Apple and Google accounts, plus signing keys and keystores | A lost signing key forces a new listing, losing reviews, rankings, and installed base |
| CI/CD pipelines, runners, and deploy credentials | The vendor's CI provider, sometimes on their own hardware | You can change code but not ship it, and the pipeline encodes steps that exist nowhere else |
| Databases, backups, and a proven restore | The vendor's managed database and backup schedule | A backup you have never restored is an assumption; prove one before the overlap ends |
| Monitoring, logging, and alert routing | The vendor's tooling accounts, paging their staff | After cutover, failures happen silently until alerts point at your people |
| Documentation, tickets, and design assets | The vendor's tracker, wiki, and design tool | Ticket history is often the only record of why a decision was made; export it while access exists |
| Contracts, licenses, and the intellectual property position | Your legal and procurement records, plus the vendor's | Confirm in writing what you own and what third-party components oblige before building on top of it |
The overlap period, and why paying for it is cheaper
The common instinct when a vendor relationship ends badly is to make the break clean and immediate. It is an expensive instinct. Reconstructing why a system is built the way it is, from source alone, is archaeology: slow, uncertain, and prone to confident wrong conclusions. Two to six weeks of scheduled access to the people who wrote it costs a fraction of that.
Structure the overlap so it produces artifacts rather than goodwill. A named person, defined hours, and a written question list produce a record; open-ended availability produces nothing. Record the sessions with consent, and put every answer that matters into your own repository rather than a chat thread you will lose access to.
- A named individual with real knowledge, not an account manager, with committed hours per week
- A session where the outgoing team performs a deployment while your team watches and takes notes
- A session tracing the two or three business rules that carry the most money or risk, in code
- A written answer to "what would you fix first, and what are you worried about"
- An agreed cut-off date, after which support is billed differently or not at all
- Payment terms that hold a final amount until the transfer checklist is signed off
Where the relationship has broken down, keep the overlap narrow and transactional: access transfer, one deployment walkthrough, and answers to a fixed question list. Even a hostile handover usually yields those, because they are concrete and finite. What you should not do is skip the overlap to make a point and then spend two months of senior time paying for it.
The first two weeks for the incoming team
Resist the urge to start reading code from the top. The goal of the first two weeks is not comprehension; it is custody. You want proof that you can build, deploy, observe, and recover the system without help. What you learn about quality along the way is a side effect, and a more honest signal than a code review.
- 1
Build it from a clean machine using only the documented setup instructions, and time it. Every undocumented step is a finding; commit the corrected instructions on day one.
- 2
Get it running locally against seeded or sanitized data, reaching every external dependency or stubbing the ones you cannot.
- 3
Inventory the accounts, secrets, and third-party services, then rotate every credential the outgoing team has seen. Rotation also reveals which credentials are actually in use.
- 4
Deploy to a throwaway environment you created yourself. If you cannot stand one up from scratch, you do not own the deployment process, whatever the pipeline configuration says.
- 5
Read the deployment history and the last six months of commits. Rollbacks, hotfix patterns, and which files change together locate the fragile areas faster than any architecture document.
- 6
Find the tests, run them, and record what passes, what is skipped, and what has failed long enough that people ignore it. Check coverage on the money paths rather than in aggregate.
- 7
Restore the most recent database backup into your own environment and run against it, while someone can still explain what you find.
- 8
Point monitoring, error tracking, and alerts at your own people, and watch a normal business day to learn the baseline noise.
- 9
Ship one small, low-risk, visible change end to end, from branch to production. That proves custody better than any handover document.
- 10
Write up the top risks, the top unknowns, and what it would take to answer each. This is the only defensible input to a decision about rewriting.
Undocumented but sound, or genuinely unsafe
Incoming teams routinely mistake unfamiliarity for danger. Most inherited code is undocumented, inconsistent, and shaped by constraints nobody recorded, yet still fundamentally sound, in the sense that it does what the business needs and can be changed without breaking. That is a very different condition from unsafe, and conflating the two is how a maintenance engagement turns into an unplanned rewrite.
The distinguishing question is whether behavior can be verified. If you can change something, observe the result, and recover when you are wrong, the code is workable regardless of how it reads. If you cannot (because there is no way to test, no way to roll back, or no way to know what production is doing), the risk is real no matter how clean the code looks.
- Undocumented but sound: odd naming, patterns that differ across eras of the codebase, thin comments, a framework version or two behind, logic that looks strange until you learn the rule behind it
- Undocumented but sound: a homegrown abstraction that duplicates a library, where the homegrown version is stable and tested
- Genuinely unsafe: no way to run the system outside production, or a build that only succeeds on one person's machine
- Genuinely unsafe: credentials committed to the repository, or one shared admin account used by everyone
- Genuinely unsafe: no rollback, no restored backups, or known unpatched vulnerabilities in the request path
- Genuinely unsafe: money, tax, eligibility, or pricing logic with no tests and no reconciliation, where an error stays invisible until a customer or auditor finds it
Fix the second list immediately, on the current codebase, before proposing anything larger. Those items are cheap relative to their consequences and they are what the sponsor will be asked about. The first list is a backlog, not an emergency, and most of it should be repaired as you work in each area.
Why the first instinct to rewrite is usually wrong
Every incoming team wants to rewrite. The urge peaks in the first month, which is precisely when your understanding of the system is at its weakest and your estimate is therefore at its worst. What looks like accidental complexity at week two is often a decade of edge cases: the customer who is invoiced differently, the state with its own tax rule, the integration partner who sends malformed records on the first of the month. A rewrite discards those quietly and rediscovers them one production incident at a time.
There is also an incentive worth naming. A rewrite lets an incoming team work in familiar tools and defer the moment they are accountable for behavior they did not design. Those are real motivations, and they are not the client's interests. Hold the line for a quarter of real delivery on the existing system, then revisit the question with evidence.
The exception is narrow and recognizable: a runtime or dependency past end of support with no upgrade path, a platform you cannot hire for at any reasonable price, or a hosting or licensing arrangement being withdrawn. Those are external deadlines rather than opinions about code quality, and they justify moving earlier, still capability by capability, with a working system in production throughout.
Common questions
- How long should the overlap with the outgoing team be?
- Two to six weeks of defined, part-time availability covers most handovers, weighted toward the front where access transfer and the deployment walkthrough happen. Longer overlaps tend to decay into on-call support that neither side manages well. Set an explicit end date and agree what, if anything, is billable after it.
- What if the outgoing team refuses to cooperate?
- Narrow the ask to concrete, finite items (account transfers, a credential list, one deployment walkthrough, and answers to a written question list) because those are the things a departing vendor will usually still provide. In parallel, start recovering what you can independently: registrar and cloud account ownership, then secrets, then the pipeline. Handle the contractual side through your own counsel; that is not an engineering decision.
- Should we do a code audit before or after the transfer?
- Before, if you still have the option to walk away or renegotiate, since the audit informs what the arrangement is worth. After, if the decision is already made, because the audit is far more accurate once you can build, deploy, and run the system yourself. In either case keep the audit bounded to a couple of weeks so it does not become the project.
- How do we know if the code quality is good enough to keep?
- Judge it on whether behavior can be verified and changed safely rather than on how it reads. Working tests around the paths that carry money or risk, a repeatable build, and a rollback you have actually performed matter more than naming conventions or framework versions. Code that is ugly but verifiable is a maintenance cost; code that cannot be tested or reverted is a business risk.
- What should we ship first after taking over?
- Something small, visible, and low-risk that exercises the entire path from branch to production. The point is to prove custody of the pipeline and to give the sponsor evidence that the transition worked, not to deliver value on day ten. Save the first substantive change until after credentials are rotated and a restore has been verified.
- Can our internal team take this on instead of another vendor?
- Often yes, provided you can dedicate senior time for the first month rather than fitting the handover around existing delivery commitments. The common failure is assigning the takeover to people who are already fully loaded, so the overlap window expires before anyone has built the system from a clean machine. If internal capacity is thin, use outside help for the transfer period specifically and keep long-term ownership in-house.