Clean Codebase Handover: Runbooks, Secrets & Access
Краткое содержание
Pixel shares a practical guide to clean codebase handovers, covering full account access, client-owned secret vaults, clean-machine builds, and runbooks for deployment, rollback, and restore. These verifiable steps help teams take ownership of their software and avoid vendor lock-in.
DEV Community
Clean Codebase Handover: Runbooks, Secrets, Zero Lock-In
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: [email protected]
vendor_access: removed
mfa: enabled
- service: cloud provider (VPS + object storage)
owner_account: [email protected]
vendor_access: member, removable
billing: client card
- service: payment gateway
owner_account: [email protected]
vendor_access: developer role
- service: transactional email
owner_account: [email protected]
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...

Powered by Readybot.io