A good software handover gives you five things from the outgoing developer or agency: ownership of every account, the complete code with its history, a way to build and deploy the app that someone else can follow, the documentation that exists, and the knowledge in their heads, captured on a recorded walkthrough. Ask for all five in writing, while the outgoing team is still engaged and paid, and plan for an overlap of a few weeks rather than a single goodbye call.
The checklist below works whether you are moving from a freelancer to an agency, from an agency to an in-house hire, or from one team to another. Send it to the outgoing team as a list, agree dates for each part, and tick items off only when someone on your side has checked them.
1. Accounts and access
Everything the app runs on should end up in your company's name, with at least two of your own people as owners.
| Item | Ask for | Check on your side |
|---|---|---|
| Code repository | Ownership transferred to your organisation | You are an owner and can see every branch |
| Hosting and cloud accounts | Account in your company's name, billed to you | You can log in and see the running servers |
| Database | Admin credentials, or access through your cloud account | You can take a backup yourself |
| Domain and DNS | Registrant changed to your company | The registrar shows your company and email |
| App store accounts | Apps under your company's developer accounts | You can see the apps and their review history |
| Payments and billing APIs | Account ownership and keys | You can log in and see live transactions |
| Email, SMS and other paid APIs | A list of every service, with ownership moved to you | Each one appears on your bill, not theirs |
| Monitoring and error tracking | Alerts routed to your team | Your team receives a test alert |
| Password manager or secrets store | All secrets handed over through it, never by email | Every secret in the list is in your vault |
If the outgoing team holds any account in their own name, make its transfer the first item on the list. Our post on what to secure in the first 48 hours after a developer leaves covers the case where the relationship has already ended.
2. Code and history
- The full repository with history, including every branch and tag, not a zip of the current files. The history explains why the code looks the way it does.
- Unmerged work: any branch in progress, with a note on its state.
- Infrastructure code and scripts: deployment scripts, server setup, Docker files, CI configuration, database migration files and seed data.
- Licences and third-party code: anything paid for, vendored in or used under a licence your company now needs to hold.
3. Environments and deployment
The single most important test of a handover: can someone who has never seen the app build it from a clean copy of the code and deploy it?
- A written runbook: how to set up a development machine, run the tests, build, deploy and roll back.
- Environment configuration: every setting and environment variable the app needs, for each environment (development, staging, production), delivered through the password manager.
- Scheduled jobs and background workers: what runs, when, and on which server.
- Backups: where they are, how often they run, and when a restore was last tested.
- A deploy done by your side: before the handover closes, someone from your team or your new team deploys a small change while the outgoing team watches.
4. Documentation that exists
Ask for whatever exists, in whatever state. Imperfect documentation is still useful.
- An architecture overview: the main parts of the system and how they talk to each other.
- API documentation, including any integrations with partners or customers.
- Data model notes: the important tables and what they mean in business terms.
- Known bugs, open tickets and the backlog, exported from whatever tool they used.
- Dependencies and their versions, with any that are close to or past their end-of-life date.
5. Knowledge in their heads
This is the part that leaves with the people, so capture it while you can.
- Recorded walkthroughs: one session on the architecture, one on the deploy, one on the parts of the code they consider fragile. Screen recordings are better than documents written in the last week.
- The "why" behind odd decisions: workarounds, strange-looking code that must not be touched, and past incidents.
- Customer-specific behaviour: settings, data fixes or features that exist for one customer.
- A contact window: agreement that they will answer questions for a few weeks after the handover, paid if necessary.
A sensible timeline
| When | What happens |
|---|---|
| Week 1 | Accounts and access move to your company; code and history handed over |
| Week 2 | Runbook, configuration and documentation delivered; first recorded walkthroughs |
| Week 3 | Your side builds and deploys from a clean copy while the outgoing team watches |
| Week 4 | Remaining questions answered; outgoing access removed; handover signed off |
Four weeks is comfortable for most apps. Shorter handovers work when the outgoing team is organised and the app is small; longer ones make sense for large systems with many integrations.
When the handover cannot happen
Sometimes the outgoing team is gone, unresponsive or unwilling. A new team can still take over if you control the code and the hosting: they reconstruct the runbook from the servers, map the accounts, list the dependencies and write the documentation that should have been handed over. That is the first step of every software maintenance and takeover engagement we run at MicroPyramid: a fixed-scope Takeover Assessment that ends with the access map, runbook, dependency register and risk list in your hands.
The checklist
- Every account in our company's name, with two of our people as owners
- Full repository with history, branches and tags
- Infrastructure code, deploy scripts and CI configuration
- Written runbook: set up, test, build, deploy, roll back
- Configuration for every environment, delivered through the password manager
- Scheduled jobs, workers and backups documented; a restore tested
- Existing documentation, backlog and known bugs exported
- Dependency list with versions and support dates
- Recorded walkthroughs of architecture, deploy and fragile areas
- A deploy done by our side before sign-off
- Outgoing access removed at the end of the handover
Frequently Asked Questions
What should a software handover include?
Ownership of every account the app uses, the complete code repository with its history, a written runbook for building and deploying, configuration for each environment, the documentation that exists, and recorded walkthroughs of the architecture, the deploy process and the fragile parts of the code.
How long should a handover from a developer or agency take?
About four weeks is comfortable for most apps: a week for accounts and code, a week for documentation and walkthroughs, a week in which your side deploys with the outgoing team watching, and a week to close questions and remove their access. Small, well-organised apps can move faster.
What is the most important item on the checklist?
Account ownership. Code and documentation can be reconstructed by a new team, but a domain, app store account or hosting account held in someone else's name can stop you from running your own product.
How do we know the handover is complete?
When someone who has never worked on the app builds it from a clean copy of the code, deploys a small change to production and rolls it back, using only the runbook and the accounts you own. Until that works, the handover is not finished.
Should we pay the outgoing developer for the handover?
If the handover is not already covered by your contract, paying for a few weeks of their time is usually money well spent. Their knowledge is the hardest part to replace, and a paid handover gets more attention than a favour.
What if the outgoing team will not cooperate?
A new team can still take over if you control the code and the hosting. They can rebuild the runbook from the servers and write the missing documentation during a takeover assessment. Check your contract on code ownership, and take legal advice if the code itself is being withheld.