Most vendor lock-in is not in the contract. It is in the things nobody wrote down: the DNS account only the agency can log into, the cron job living on a server nobody remembers, the .env file that exists on one laptop. A codebase handover fails when the new team receives the repository but not the ability to run, deploy and recover it. A clean handover is a checklist you can verify, not a meeting.
At Loop Origin I build and maintain custom web applications on Laravel, Vue, Nuxt and PostgreSQL, and I have spent nine years as a Principal Software Engineer receiving and handing over production systems. I wrote this with help from AI tools and checked every command and config myself. This guide covers what a client or CTO should demand at handover, and how an engineering team proves it was delivered.
What does a clean codebase handover include?
Direct answer: A clean handover gives the new owner five things they can verify alone: full admin access to every account, a repository that builds from a clean machine, secrets in a vault they control, runbooks for deploy, rollback and restore, and architecture notes explaining why the system looks the way it does. If any step needs the old vendor, lock-in remains.
Where lock-in actually hides
When I audit an inherited system, the code itself is rarely the problem. The problem is everything around it.
| Layer | Typical lock-in | How you find it | What "handed over" means |
|---|---|---|---|
| Accounts | Domain, DNS, cloud and email owned by the vendor's login | List every bill and every login screen | Client is the owner; vendor is a removable member |
| Secrets | API keys in a dev's .env, a chat thread or the server only | grep the server, ask "where does this key live?" | Every secret in a client-owned vault, rotated after transfer |
| Build | Works only on one laptop or one CI runner | Fresh clone on a clean VM | Documented one-command setup that passes on a clean machine |
| Infrastructure | Hand-configured VPS, undocumented cron, manual Nginx edits | Diff the server against the repo | Config in the repo or written down, cron listed in the scheduler |
| Data | Backups in the vendor's storage bucket | Ask for a restore, not a backup | Client-owned backup storage plus a tested restore |
| Knowledge | Decisions only in someone's head | Ask "why" on five odd design choices | Short architecture decision records |
Step 1: Transfer accounts before code
Start with ownership, because it is the hardest thing to fix later. Make a register of every external account the system depends on.
# handover/accounts.yml (no secrets here, only ownership facts) - service: domain registrar owner_account: it@client.example vendor_access: removed mfa: enabled - service: cloud provider (VPS + object storage) owner_account: it@client.example vendor_access: member, removable billing: client card - service: payment gateway owner_account: finance@client.example vendor_access: developer role - service: transactional email owner_account: it@client.example vendor_access: removed The rule is simple: the client's company email is the owner of every account, the vendor is a member who can be removed in one click, and multi-factor login is not tied to a vendor engineer's phone.
Step 2: Prove the repository builds from zero
A repository that only builds on the original developer's machine is not handed over. Give the new team a single entry point and test it on a fresh virtual machine.
# Makefile setup: cp -n .env.example .env docker compose up -d db redis composer install --no-interaction npm ci php artisan key:generate php artisan migrate --seed npm run build check: php artisan test npm run lint Then add a guard so .env.example cannot silently drift from what the code actually reads:
#!/usr/bin/env bash # scripts/check-env-example.sh set -euo pipefail used=$(grep -rhoE "env\('([A-Z0-9_]+)'" config app | sed -E "s/env\('//" | sort -u) listed=$(grep -oE '^[A-Z0-9_]+' .env.example | sort -u) missing=$(comm -23 <(echo "$used") <(echo "$listed")) if [ -n "$missing" ]; then echo "Missing from .env.example:"; echo "$missing"; exit 1 fi echo ".env.example covers all env() keys" Run it in CI. It turns "we forgot to tell you about that key" into a failing build.
Step 3: Move secrets into a vault the client owns
Secrets are where handovers leak. Pick one place the client controls: a password manager with shared vaults, the cloud provider's secret manager, or encrypted files in the repo with a tool such as SOPS and age keys held by the client.
# .sops.yaml (encrypted files can live in git; only key holders decrypt) creation_rules: - path_regex: deploy/secrets/.*\.enc\.yaml$ age: age1clientprimarykey..., age1clientbackupkey... After the transfer, rotate everything the old team could see: database passwords, API keys, OAuth client secrets, SSH keys and deploy tokens. Rotation is the only proof that former access is gone. Keep a list of what was rotated and when.
Step 4: Write the runbooks people will actually use
A runbook is a page someone follows at 2 AM. Keep each one short and testable. The minimum set I hand over:
| Runbook | Must answer | How to verify it works |
|---|---|---|
| Deploy | How code reaches production, who can do it | New engineer deploys a trivial change |
| Rollback | How to return to the previous release in minutes | Roll back that change on purpose |
| Restore | How to restore the database to a point in time | Restore last night's backup to staging |
| Scheduled jobs | Every cron or scheduler task, its owner and failure alert | Compare list to the server's crontab |
| Incident | Where logs live, who to call, status page steps | Walk through a past incident |
| Access | How to add and remove a team member everywhere | Remove a test user from all systems |
The restore runbook matters most. A backup nobody has restored is a hope, not a plan. I go deeper on recovery targets in SaaS Backup & Disaster Recovery: RPO, RTO and PITR.
Step 5: Record why, not just what
New owners struggle less with what the code does than with why it was built that way. Short architecture decision records solve this.
# ADR-007: Queue payment webhooks instead of processing inline Date: 2026-03-12 Status: accepted Context: Gateway retries webhooks if we respond slowly; inline processing caused duplicates. Decision: Store raw webhook, return 200, process in a Redis-backed queue with an idempotency key. Consequences: Needs a worker running; failed jobs alert to the ops channel. Ten of these explain more than a hundred pages of generated documentation. Add a one-page system map: services, data stores, external APIs and where each runs. External dependencies deserve their own list with versions and deprecation dates, which I covered in Third-Party API Deprecations: Catch Them Before Prod.
Handover models compared
How much effort a handover needs depends on who takes over next.
| Model | Best when | Main risk | Handover effort |
|---|---|---|---|
| Hard cutover to in-house team | Client has hired engineers already | Knowledge gap in the first incident | High: full runbooks and paired sessions |
| Shadow period (2–6 weeks) | New team exists but is new to the system | Cost of two teams at once | Medium: new team deploys, old team watches |
| New agency takes over | Client stays outsourced | Same lock-in repeats with the new vendor | High: insist on the same checklist again |
| Hybrid: in-house owner plus retainer | Small team, needs senior backup | Unclear responsibility | Medium: clear on-call and access rules |
My default recommendation is the shadow period. The new team does every deploy, rollback and restore while the original team is still available to answer questions. Problems surface while help is cheap.
The handover acceptance checklist
The client signs off only when each item passes without help from the old vendor.
- Client accounts own the domain, DNS, cloud, email, payment and monitoring services.
- Vendor access is a removable member role on every account, or is already removed.
- A new engineer cloned the repository on a clean machine and ran
make setupandmake checksuccessfully. -
.env.examplelists every key the code reads, enforced in CI. - All secrets live in a client-controlled vault, and every secret the vendor saw has been rotated.
- Server configuration, including web server, PHP-FPM, workers and cron, is in the repo or documented.
- A backup was restored to staging during the handover, with the time it took recorded.
- Deploy and rollback were each performed by the new team at least once.
- Architecture decision records and a one-page system map are in the repo.
- License files and third-party paid services are listed with owners and renewal dates.
FAQ
How long should a codebase handover take?
For a typical business web application, plan a few weeks, not a few days. Account transfers and secret rotation are quick; proving deploys, rollbacks and restores with the new team takes the time. A shadow period of two to six weeks is common for systems in active use.
Who should own the cloud and domain accounts during development?
The client, from day one. The agency should be a member with the access it needs. This removes the hardest part of any future handover before it starts.
Is code ownership in the contract enough?
No. A contract can say you own the code, but if you cannot build, deploy or restore it without the vendor, you are still dependent. Ownership has to be operational, which is why the checklist tests actions, not documents.
Do we need to rotate secrets if we trust the old vendor?
Yes. Rotation is not about trust; it is about knowing exactly who can access production. Former contractors' laptops, chat history and CI logs may still hold keys long after the relationship ends.
What documentation actually matters?
Runbooks for deploy, rollback, restore and access, a system map, and short decision records. Large auto-generated API documents rarely help in a real incident.
Can we keep the old vendor on a small retainer?
Often that is a good idea for the first months. Keep their access limited and time-bound, and make sure every task they do is written into the runbooks so knowledge moves to your team.
The short version
A handover is done when your team can run, change, deploy and recover the system without calling anyone. Transfer accounts first, prove a clean build, move and rotate secrets, test every runbook by doing it, and write down the reasons behind odd decisions. Anything left undone is lock-in, whatever the contract says.
Follow & Connect
- LinkedIn: Loop Origin
- X: Muhammad Ali Mughal (@AliMughal887)
- GitHub: Loop Origin (@LoopOrigin)
Watch on YouTube: Resume Boost AI · PixelValut · Daily AI News By Ali




