On this page
In short
- A handover isn't a document at the end. It's the point where your team can run, change and recover the system without the people who built it.
- Ownership of repositories, cloud accounts and third-party services should already be yours. Handover confirms it and moves the last credentials.
- Runbooks and alerts matter more than long design documents. Your team needs to know what to do when something breaks.
- Prove the handover works: have your team deploy, roll back and respond to a test alert while the builder is still available.
What a handover is for
The test of a handover is simple: could your team keep the system running, fix a bug and ship a small change if the original builder were unreachable? If the honest answer is no, the handover isn't done, however much documentation has been delivered.
That's why handover belongs in the scope from the start. It's much easier to build a system that can be handed over, with everything in code, in your accounts and written down as it goes, than to reconstruct that knowledge at the end.
The handover is done when your team has deployed and recovered the system themselves.
Code, infrastructure and pipelines
- Repositories. Every repository in your organization's source control, with full history, not a zip file. Include anything that looks like a side project: scripts, data migrations, test fixtures.
- Infrastructure as code. The cloud resources defined in AWS CDK, CloudFormation, Terraform or similar, so the environment can be recreated or reviewed without clicking through a console.
- Deployment pipelines. The CI/CD configuration in your repositories and running under your accounts, using credentials your team controls.
- Environments. A list of every environment (development, test, production), what each is for, and how data gets into it.
- Dependencies. Third-party libraries and services, their licenses, and anything with a renewal date or an expiring key.
Access and credentials
Credentials are the part of a handover most likely to be done casually and the part where casual is most expensive. Treat it as a small project of its own:
- Inventory. List every account, key and secret the system uses: cloud accounts, database logins, API keys, signing certificates, domain registrar, email and SMS providers, app store accounts.
- Move ownership. Anything registered to the builder moves to your company, with billing on your side.
- Store properly. Secrets live in a secrets manager or vault your team controls, never in a document, spreadsheet or chat message.
- Rotate. Once your team holds everything, rotate the secrets the builder had access to, and confirm the system still works.
- Remove access. The builder's personal and service access is removed or reduced to whatever ongoing support you've agreed, and you can see that it's gone.
Monitoring, alerts and runbooks
A system without monitoring tells you it's broken through a phone call from a user. Before handover, confirm what's watched, who hears about it, and what they're expected to do.
Operational pieces to receive at handover and what to check
Dashboards
- What to check
- They show the health of the things your business cares about, not only CPU and memory
Alerts
- What to check
- Each one goes to a person or rota on your side, not to the builder's inbox
Runbooks
- What to check
- Each alert links to a short page: what it means, how to confirm it, what to try first
Logs
- What to check
- Your team can find the logs for a failed request and knows how long they're kept
Backups
- What to check
- Backups exist, and someone has restored one to prove it works
Routine tasks
- What to check
- Certificate renewals, key rotations and dependency updates are written down with an owner
| Piece | What to check |
|---|---|
| Dashboards | They show the health of the things your business cares about, not only CPU and memory |
| Alerts | Each one goes to a person or rota on your side, not to the builder's inbox |
| Runbooks | Each alert links to a short page: what it means, how to confirm it, what to try first |
| Logs | Your team can find the logs for a failed request and knows how long they're kept |
| Backups | Backups exist, and someone has restored one to prove it works |
| Routine tasks | Certificate renewals, key rotations and dependency updates are written down with an owner |
Documentation that gets used
Long design documents are rarely read after launch. The documentation that earns its keep is short, current and kept next to the code:
- Architecture overview. One diagram and a page of text: the main parts, how data flows between them, and which systems outside it depends on.
- Setup guide. How a new developer gets the system running locally and makes a first change.
- Deployment and operations guide. How releases go out, how to roll one back, and how to scale or restart things.
- Decision records. Short notes on the choices that look strange without context, and why they were made.
- Integration notes. For each connected system: what's read or written, which account is used, and who owns it on your side.
Planning a build with handover in mind?
On a scoping call we'll talk through what your team will need to run the system, and write it into the scope so it's part of the fixed price rather than an afterthought.
Not ready to talk yet? Draft a project brief first
Knowledge-transfer sessions
Documents capture what someone thought to write down. Sessions with the people who'll own the system catch the rest. A useful set covers:
- Architecture walkthrough. The builder explains the system end to end and answers questions, ideally recorded.
- Code tour. Where the important logic lives, how it's tested, and the parts that need the most care.
- Supervised deployment. Someone on your team ships a small change through the pipeline while the builder watches.
- Rollback and recovery. Your team rolls back a release and restores from a backup in a non-production environment.
- Test incident. Trigger an alert on purpose and have your on-call person follow the runbook.
The last three turn a handover from a presentation into proof. Anything that goes wrong during them is a gap in the documentation, found while it's still cheap to fix.
Support after handover: the options
Some teams want a clean break; others want the builder on call for a while. Any of these can work, as long as it's chosen and written down rather than assumed:
Common post-handover support arrangements
Warranty window
- What it covers
- Fixes for defects against the agreed scope, for an agreed period
- Good fit when
- You want reassurance that launch issues will be fixed
Support agreement
- What it covers
- Help with incidents and questions on agreed terms
- Good fit when
- Your team is new to the stack or the cloud platform
Change work as needed
- What it covers
- New features or changes, quoted one piece at a time
- Good fit when
- The system is stable and changes are occasional
No ongoing arrangement
- What it covers
- Your team owns everything from handover
- Good fit when
- You have the in-house skills and want a clean break
| Option | What it covers | Good fit when |
|---|---|---|
| Warranty window | Fixes for defects against the agreed scope, for an agreed period | You want reassurance that launch issues will be fixed |
| Support agreement | Help with incidents and questions on agreed terms | Your team is new to the stack or the cloud platform |
| Change work as needed | New features or changes, quoted one piece at a time | The system is stable and changes are occasional |
| No ongoing arrangement | Your team owns everything from handover | You have the in-house skills and want a clean break |
Whatever you choose, agree what counts as a defect versus a change, how issues are reported, and how the arrangement ends. Settling those three points up front means they aren't argued about after launch.
Handover checklist
Confirm each item before the builder steps back
- All repositories are in your organization, with full history.
- Infrastructure is defined as code, and nothing in the cloud account was created by hand.
- Pipelines run under your accounts with credentials your team controls.
- Every account, key and certificate is inventoried, owned by your company and stored in your secrets manager.
- Secrets the builder could see have been rotated, and the builder's access is removed or reduced as agreed.
- Every alert goes to someone on your side and links to a runbook.
- A backup has been restored successfully.
- The architecture overview, setup guide and operations guide are current.
- Your team has deployed a change, rolled one back and handled a test alert.
- Any support arrangement after handover is written down, including how it ends.
Our How we work page describes how we handle ownership and handover. If you're earlier in the process, see questions to ask before hiring a software development firm, and if the system will be your first on AWS, AWS foundations for a first custom app.
See it applied
- Illustrative sample. Not client work.See a sample scope for an internal tool →An invented request and approval portal that replaces a spreadsheet and email, on an existing SQL Server database with the company's existing single sign-on.
- Illustrative sample. Not client work.See a sample handover package →The handover index for an invented plant-floor dashboard: repositories, infrastructure as code, the pipeline, runbooks, a data dictionary, the credential handover list, alerts, known limitations and sign-off.
Share this guide
Related services
Topics