Software handover checklist: could you deploy without us?

I run a software firm in Dhaka, and this month we are handing over a platform we built and have looked after for a client for several years. They have hired their own engineering team, which is the best reason I know of to bring a system in-house. The new team is good, the documentation site is up, and to be honest I thought we had the handover well covered. Then their questions started arriving, and every one of them was better than the checklist we had written.

"Can you show us a deploy to production with no staging server in between?"

"When your staging server goes away, what exactly changes in our pipeline?"

"Where do the secrets live, and which ones are yours?"

"Has anyone actually restored from the backup?"

Well, none of those are really questions about documentation. They are questions about whether the client can run the thing without us, which is the only test of a handover that matters.

So I have sat down to write the checklist I wish they had been able to find. Please keep in mind that we are the vendor in this story, and read it as carefully as you like.

(If you only want the list, then please skip ahead to the checklist, though do read the three tests after it.)

What is a software handover document?

A software handover document is the record a vendor leaves behind so that people who did not build a system can run it and change it. In practice it is a set rather than a single document: the architecture, the environment, the pipeline, the credentials inventory, the runbooks and the list of what is fragile.

It is not a project completion report. A completion report says what was delivered, and a handover says how to keep it running. Plenty of projects close with a thorough completion report and no handover at all, and the business finds out a year later, when it needs to ship a fix and nobody can.

When does a project handover happen?

In order to answer that honestly I have to give an answer that sounds like a dodge. On a well-run engagement, it should not really happen at all.

If the code has been in your repositories since the first commit, the domain is in your registrar, the cloud account is in your name and the documentation was written as the work was done, then there is nothing to transfer at the end. The vendor removes its own access and leaves. What is left is a week of checking rather than a month of moving.

Handovers are painful because most engagements are not run that way. The assets pile up on the vendor's side for eighteen months and then somebody tries to move them all in a fortnight. So please read the rest of this as a test paper rather than a moving checklist: what should be true from day one if you are starting, and what to check if you are ending.

Why would you leave a vendor you are happy with?

I want to deal with this first, because a page like this can read as if engagements only end when something has gone wrong, which is rarely the case.

Deloitte's 2024 Global Outsourcing Survey asked exactly this. 70% of the executives surveyed had brought outsourced work back in-house in the past five years, and the survey's own heading on the reasons reads "It's not dissatisfaction with outsourced services." Of those planning to bring more work in-house, 82% said their vendors were meeting or exceeding expectations. The reasons were control, and wanting the capability inside the company. The vendor did its job and the client outgrew the arrangement.

A satisfied client takes a system in-house because —

• They hired a CTO or an engineering team, usually around product-market fit.
• They were acquired, and the acquirer already has a vendor or wants fewer of them.
• The product went into maintenance mode, and a system that changes twice a year needs a runbook and someone on call, not a delivery team.
• Their regulator expects an exit plan that has actually been exercised.
• The money changed shape: a grant ended, or spend moved from projects to headcount.

None of those are complaints. All of them end at the same checklist, and if we have done our job it is a boring one by then.

What is a build-operate-transfer engagement?

There is an engagement model built on the idea that handing over is the point. In a build-operate-transfer arrangement the vendor builds the team and the system, runs it for an agreed period, and then transfers the people, the code and the operation to the client on an agreed trigger. Deloitte found that half the organisations it surveyed had used a version of it to set up in-house centres.

You do not need that contract to get the benefit, though. Any engagement can be run as if transfer is the end state from the first week, which is what the checklist below describes.

Is an exit plan a sign of distrust?

No. For many of our clients it is a regulatory obligation, and a vendor that turns up with the plan already written is taking a compliance job off their desk.

If you are a bank, your supervisor already expects a documented and tested exit plan for any critical outsourced function; the European Banking Authority's outsourcing guidelines say so in those words. The UK's Prudential Regulation Authority separates a "stressed exit", where the provider fails, from a "non-stressed exit", a planned exit for commercial or strategic reasons. The EU's Digital Operational Resilience Act adds a transition period and the return of data in a usable format. Bangladesh Bank's ICT Security Guideline requires banks here to hold a contingency plan for critical outsourced services, to state ownership of software and documentation in the contract, and to follow a documented termination process.

Outside banking the same idea appears in narrower forms: the GDPR requires a processor to return or delete personal data when the service ends, HIPAA requires the same for protected health information, and ISO 27001 expects supplier agreements to say what happens to information, access and intellectual property at the end.

So when a client asks us for an exit plan, they have usually read their own obligations, and the checklist below is what we hand them.

Three shapes of lock-in

The failure modes depend on how the engagement was set up, and I will take them in turn —

An MVP build: who owns what?

Ownership problems are the ones that end up in front of lawyers, and they are usually decided in the first week. The story is nearly always the same: the repository lives in the agency's account, the domain was registered by the agency because it was quicker, and the hosting, app store, analytics and payment accounts are in the agency's name because the agency set them up. Nobody did this on purpose; it was the quickest way at the time. Then the founder wants to leave, and finds out that the word for their situation is "hostage".

The rule that avoids all of this is short. The agency gets access, never ownership —

• The repository is in your organisation from the first commit; the agency's engineers are members of it.
• The domain is registered to your company, in a registrar account you hold.
• The cloud account is yours, billed to you, with the agency holding a role inside it.
• Every third-party service is signed up under an email alias your company controls.
• The contract assigns the intellectual property to you in wording that transfers now. US courts have held that "will assign" is a promise, not a transfer. Wherever you are, please have a lawyer read that one sentence.
• Nothing in the build depends on a framework or platform only the agency can run.

The questions to put to an agency before it becomes a problem are in how to choose an MVP development agency. Our MVP development page sets out how we run a build so that version two does not start with a rescue.

A dedicated team: can you run it without us?

When a vendor runs delivery for you over several years, ownership is usually fine. The subtler problem, the one our client's questions were circling, is that the vendor knows how to operate the system and you do not. That knowledge comes down to six things, and all of them can be written down —

• The pipeline: which file builds and deploys production, which branch triggers it, and which steps are manual gates. Any staging pipeline pointed at the vendor's own servers is named as theirs and removed before they go.
• The variables and secrets: an inventory of every environment variable by name and purpose, and where each one lives. The values travel separately through an agreed secure channel, never in the documentation.
• The host: the server specification recorded from the running machine, plus anything that runs outside a container, such as scheduled tasks or log settings, with the steps to recreate them. These are what a rebuilt server silently loses.
• The deploy, recorded: a runbook per repository and a short screen recording of a real deployment that follows it.
• The restore: a recovery runbook that states its own limits, such as how old the data will be, what a snapshot does not carry (DNS, secrets, scheduled tasks, integrations), and how to stop a restored copy from sending live email or taking payments.
• The debt: a register of known workarounds and fragile areas, kept as a file rather than mentioned in the last meeting.

Firstly, notice that every item on that list can be checked by someone who did not write it. Secondly, none of it is difficult. The problem is that there is never a natural time to do it, so unless the engagement produces it as it goes, it does not get done. Our dedicated development team page describes how we run one that way.

Augmented engineers: where does the knowledge live?

Under staff augmentation the checklist is mostly yours to run. When our engineers work inside your team, under your process and architecture, we never hold your assets in the first place. The risk is a different one: after a year, the only people who understand a particular service are the augmented ones. What works against that is pairing treated as delivery rather than training, an in-house owner for context transfer, and a quarterly look at who can safely change each part of the system. We have written that up in staff augmentation risks; our staff augmentation page sets out how we run those engagements.

The software project handover checklist

Here is the whole thing. The middle column is what "yours" looks like. The right-hand column is how you check it without taking anybody's word for it. Where it names a test, that test is described in the next section —

Item	What "yours" looks like	How you verify it
Source code and IP	Repository in your organisation from the first commit; IP assigned in wording that transfers now	Repository settings; the clause
Domain and DNS	Registrant is your company; DNS in an account you hold	WHOIS; a login you have used
Hosting and billing	Cloud account in your name, invoiced to you	Root login; the last invoice
Third-party accounts	App stores, analytics, payments, email, social, under an alias you control	Reset a password on each
Architecture and decisions	Diagram and decision records dated from the work	The dates
Production server	Specification recorded from the running machine	Compare to the provider's console
Deployment	Runbook per repository plus a recording of a real deploy	Test 1: deploy without us
Pipeline	Production pipeline named; any vendor staging pipeline marked for removal	Read the pipeline settings
Variables and secrets	Inventory of names and purpose; values delivered separately	Every name exists in your settings
Host configuration	Scheduled tasks, daemon and log settings, with recreation steps	Rebuild on a clean machine
Database	Schema documented; migration history in the repository	Run migrations on a restored copy
Backups and recovery	Backups confirmed at the provider; a runbook that states its limits	Test 2: restore without us
Repository mirrors	Exact replicas; direction and credentials documented	Compare the latest commits
Technical debt	A register with the workaround and the risk for each item	It exists as a file
Documentation accuracy	The docs describe what the system actually is	Spot-check one claim
Warranty and support	Separate lines, with dates	Read the agreement
Vendor exit	A list from the vendor of what it removes on its side	Test 3: revoke us

That is seventeen lines. Longer lists exist, and most of the extra length is meeting minutes and sign-off forms. What they usually lack is the right-hand column.

How do you know the handover worked?

You run three tests. Our client asked for the first two in their own words. The third is one most vendors would rather not bring up.

Test 1: deploy without us

One of your engineers ships a small change to production using only the runbook and the recording, without asking anyone at our end. If they have to ask, the documentation has failed, and the fix goes into the documentation.

Test 2: restore without us

Restore a backup into an isolated environment and run the main flows. This proves the backup exists, that the runbook is real, and that the restored copy cannot send email or take payments. A backup setting in a console cannot tell you whether the backup is of any use; this test can.

Test 3: revoke us

We give you a written list of everything we remove on our side: our engineers' keys, our staging pipeline and its variables, our OAuth applications, our seats in your tools. You revoke our access. Then you run test 1 again. If it still passes, the handover is done.

Well, I will admit the third test is not comfortable to write down, because it commits us to something in public, and that is exactly why it belongs here. Most engagements end for reasons that have nothing to do with the vendor, and the only question then is whether leaving takes a week or a quarter.

Do you need source code escrow?

Probably not for a system built for you, and quite possibly yes for software you license. Escrow exists for the case where you never receive the source. For a bespoke build with the repository in your organisation since the first commit, you already hold what an escrow agent would release to you, every day rather than after a dispute. So if a vendor offers escrow on a custom build, please ask the simpler question first: why is the code not already in my account?

What our contract actually says

Let us be specific. Our agreements commit us to handing over three things when an engagement ends: the source code, the credentials, and the process documentation. The checklist above is the third of those unpacked, the same promise written out so you can check it line by line.

"Of course we will hand everything over" is what every vendor says, and it costs nothing to say once the invoices have stopped. What you want is the clause, and a checklist you can check against it yourself. So please ask every firm on your shortlist, ours included, to show you where it is written and which of the three tests they would run.

Where this leaves you

If you are about to start an engagement, please spend the first hour making the repository, the domain, the cloud account and the service logins yours, before anybody writes a line of code. Everything else here becomes easy once that is done.

If you are bringing a system in-house, run the three tests before the vendor's last day. It is far better to find out that nobody can deploy while the people who can are still answering their email.

And if you are choosing a vendor for a longer build, our dedicated development team page sets out how we keep the documentation current as we go.

I hope this checklist has been to some aid to you. If you think we have missed a line, or you have run a handover test we should add, do let me know. Thanks!

Sources

• Build-operate-transfer definition: Morgan Lewis, Rise of the BOTs, June 2024.
• European Banking Authority, Guidelines on outsourcing arrangements (EBA/GL/2019/02), section 15, exit strategies.
• Prudential Regulation Authority, SS2/21 Outsourcing and third party risk management, chapter 10 (stressed and non-stressed exit); FCA Handbook, SYSC chapter 8.
• Regulation (EU) 2022/2554 (DORA), Articles 28 and 30.
• Bangladesh Bank, Guideline on ICT Security for Banks and Non-Bank Financial Institutions, fourth edition (2023), chapter 12, Service Provider Management.
• GDPR Article 28(3)(g); HIPAA Privacy Rule, business associate contract requirements (45 CFR Part 164); ISO/IEC 27002:2022, information security within supplier agreements.
• "Will assign" versus present assignment: Advanced Video Technologies v. HTC, US Court of Appeals for the Federal Circuit, 2018 (US law; UK readers should take advice on the equivalent position).