Process
Project Handover
Project handover is when the work of building an application transitions from one team (agency, contractor, freelancer) to another (in-house team, maintenance vendor, another agency). If it's done well, the receiving team can pick up where the previous team left off. If it's done poorly, the receiving team spends months figuring out what was built and how to change it. Good handovers are deliberate and documented.
What a Good Handover Looks Like
A good handover has these elements:
- All access is transferred. Repository, hosting, databases, domains, third-party services—the receiving team can reach everything they need.
- Credentials are secure. Passwords, API keys, and secrets are passed securely (not in a text file), and access is verified.
- Documentation is complete. Architecture overview, how to run locally, deployment process, known issues, and contact info for the previous team are written and reviewed.
- Knowledge sessions happen. The team that built it explains key decisions, pitfalls to avoid, and how to approach common problems.
- Code is clean and maintainable. Technical debt is documented. If there are shortcuts or hacks, the receiving team knows what they are and why they're there.
- Ownership is clear. Who is responsible for what? The receiving team owns the code, or is ongoing support expected from the original builder?
Handover Scenarios
Handovers happen in different contexts:
| Scenario | From | To | Key Challenges |
|---|---|---|---|
| Agency to In-House | External agency/freelancer | Company's own team | Team doesn't know the codebase, agency has all the context. Knowledge transfer is critical. |
| Maintenance Vendor | Development team | Maintenance/support vendor | Vendor needs to understand production operations and common issues. Clear runbooks are essential. |
| Replatform | Old codebase/team | New codebase/team | Usually there's a transition period where both teams work together. Clear cutover date. |
| Open Sourcing | Company | Community | Release source code, set up governance, transition ownership. Legal review needed. |
The Handover Checklist
Before handover is complete, verify you have:
Repository Access
- Receiving team has admin access to the Git repository
- All source code is in the repository (no files that are "only on the developer's machine")
- All branches are accounted for; irrelevant branches are deleted
- Git history is clean—rebase or squash messy commits before handover
- Branch protection rules are set up (main branch requires reviews, tests pass, etc.)
Infrastructure & Hosting
- Admin access to the hosting platform (AWS, Vercel, DigitalOcean, etc.)
- Admin access to the database (if separate from hosting)
- Admin access to CDNs, load balancers, or other infrastructure
- CI/CD pipeline access and configuration documented
- Backup strategy documented—how often, where backups are stored, how to restore
Domain & DNS
- Receiving team can edit DNS records
- Domain registrar access transferred or shared
- SSL/TLS certificates are managed and expiration dates known
Credentials & Secrets
- Third-party API keys (payment processor, email service, etc.) transferred securely
- Database passwords, admin credentials transferred securely
- OAuth keys and secrets transferred and reconfigured if needed
- No credentials in source code or config files—use environment variables
- Use a password manager (LastPass, 1Password, Bitwarden) for secure credential sharing
Third-Party Accounts
- Payment processor (Stripe, Square) ownership transferred
- Analytics (Google Analytics, Mixpanel, Segment) transferred
- Email service (SendGrid, Mailgun) transferred
- SMS/push notification service transferred
- Monitoring and logging service (Datadog, New Relic, LogRocket) transferred
- CDN configuration (CloudFlare, AWS CloudFront) transferred
Documentation
- README with setup instructions
- Architecture overview—what are the major components
- How to run the app locally (with all dependencies listed)
- Environment variables needed and what they do
- Database schema overview
- Deployment process—how does code get to production
- Monitoring and alerting—what's being watched
- Known issues and workarounds
- Contact info for the previous team in case questions arise
Credentials: Security First
Never pass credentials in plaintext files or emails. These are the common ways to do it wrong:
- Email a password
- Paste it in a text file that sits in Slack forever
- Commit it to a Git repository (even in a private branch)
- Write it on a post-it note
Do this instead:
- Use a password manager with team support: LastPass, 1Password, or Bitwarden let you share credentials with team members. They're encrypted, access is logged, and you can revoke access when someone leaves.
- Change passwords after sharing: If you had to share a password, change it afterward. Only the receiving team has the new one.
- Rotate API keys: For API keys and tokens, rotate them during handover. Disable old keys so the previous team can't access production.
- Set up SSO/OAuth where possible: Instead of credentials, use single sign-on so people authenticate with their company account.
Knowledge Transfer Sessions
Documentation gets you 80% of the way. Knowledge transfer sessions close the gap.
Plan for 2–4 sessions (1–2 hours each) where the original team explains:
- Session 1: Architecture & Design Why the system is structured this way. What were the key trade-offs? What would you do differently if building from scratch?
- Session 2: How to Develop Where to add features, common patterns, how to test locally, what to watch out for.
- Session 3: Operations & Deployment How to deploy, what to watch after deployment, how to roll back, how to debug production issues.
- Session 4: Q&A & Deep Dives The receiving team asks about anything unclear. Go deep on complex areas.
Record these sessions if possible. A new team member can watch a recording instead of asking the same questions again.
Code Quality Before Handover
The receiving team will inherit the code as it is. If it's messy, they'll be frustrated. Spend time before handover cleaning it up:
- Delete dead code—commented-out sections, unused functions, obsolete branches
- Remove hack comments that don't explain the hack—replace with clear explanation or, better, fix the hack
- Document debt explicitly—if there's a shortcut or known issue, add a comment or a document
- Add tests for critical paths—at least so the receiving team can verify changes without breaking things
- Run linters and formatters—consistent style is easier to maintain
A few hours spent cleaning up saves weeks of frustration for the receiving team.
Staged Handover vs Cutover
Two approaches to transition ownership:
| Approach | How It Works | Pros | Cons |
|---|---|---|---|
| Staged | Receiving team gradually takes on more responsibility over weeks. Original team supports them. | Lower risk. Issues are caught early. Team builds confidence gradually. | Longer transition. More coordination needed. Original team is partially committed. |
| Cutover | At a specific moment, ownership transfers fully. Original team steps away. | Clear ownership. Faster. Receiving team is forced to own the problem. | Higher risk. If things break, receiving team is alone. Pressure and stress. |
Staged is safer, especially for complex systems. Example timeline:
- Week 1: Receiving team watches original team deploy. They observe and ask questions.
- Week 2: Receiving team deploys under original team's supervision. Original team is ready to step in.
- Week 3: Receiving team deploys alone. Original team is on-call for issues.
- Week 4: Ownership transfer complete. Original team is available for consultation but not responsible.
Ownership vs Ongoing Support
Be explicit about what happens after handover:
- Full ownership: The receiving team owns the code. The original team is gone. This is the goal for most handovers.
- Ongoing support: The original team stays involved for a period (say, 3 months) to help with issues, answer questions, and help the receiving team debug production problems.
- Retainer: The original team continues with a small contract (e.g., 10 hours/month) for questions and emergencies.
What's right depends on complexity and the receiving team's expertise. A simple app handover to an experienced team might need zero ongoing support. A complex system to a junior team might need 3 months of support.
Post-Handover Verification
After the official handover, verify that the receiving team can really operate independently:
- They can run the app locally from the README
- They can deploy to staging and production without help
- They can debug and fix a production issue
- They can make and deploy a small feature change
- They know who to ask if they have questions (maybe the original team, maybe internal docs)
If any of these fails, handover isn't complete. Go back and fix what's missing.
Signs Handover Went Wrong
The receiving team can't run the app locally. Setup is undocumented. The README is missing instructions. Multiple things don't work.
The receiving team is afraid to change the code. They don't understand it well enough. Tests are missing. Architecture is unclear.
Deployments fail or break production regularly. The receiving team doesn't understand the deployment process. Monitoring isn't set up. Runbooks are missing.
The original team is still critical to operations. The receiving team calls them constantly. This team can't do their job without the original team. Lock-in succeeded (the bad kind).
The Next Phase
After handover, the receiving team is responsible. They'll improve the code, add features, refactor what they don't like, and build their own patterns. That's healthy. The goal of handover is to make that possible.
The next section covers Communicating with Developers—how to work effectively with the team that's now responsible for your code.