Home / Guides / Take over another developer's code

Guide · Handover runbook

Taking over another developer's code — the complete handover checklist

Whether the last developer left on good terms, vanished mid-project, or is handing over to a new team, the takeover process is the same: transfer every account, rotate every secret the same day, prove you can build and deploy without them, audit the licences, and write down what you learn while it is still fresh. This is the runbook we use on every rescue engagement — it works whoever you hire next, including nobody.

App rescue service →All guides

In short

A safe developer handover has five stages, in this order. (1) Transfer ownership — not just access — of every account: repositories, CI/CD, cloud console, domain, DNS, database, error tracking and analytics. (2) The day the old developer loses access, rotate every secret they ever held: API keys, database passwords, deploy keys, OAuth secrets, webhook signing secrets. (3) Run an orientation pass: clean-machine install, environment reproduction, test suite, and map what is deployed against what is in the repository. (4) Audit licences and dependencies for copyleft, unlicensed snippets and expiring API plans. (5) Write down everything you learned in week one, because that is when documentation debt is cheapest to pay. If the old developer is unreachable or hostile, skip to the recovery section below.

Stage 1 — access transfer

Transfer ownership of everything, not just access to it

The single most common handover mistake: accepting collaborator access to a repository the old developer still owns. Collaborators can be removed in one click; owners cannot. The test for every item below is not "can I log in?" but "can anyone else lock me out?"

Procedures last verified July 2026

Asset	What "done" looks like	Common trap
Source repositories	Full ownership transfer into a GitHub/GitLab organisation you own (GitHub: Settings → Danger Zone → Transfer ownership). History, issues and releases come with it.	Being added as a collaborator, or receiving a zip of the code with no git history.
Org & team accounts	Your own organisation, with billing in your company's name and you as the sole org owner. The old developer becomes an outside collaborator you can remove.	The "company" org was actually the freelancer's personal org all along.
CI/CD	Pipeline accounts (and their stored environment secrets) under your ownership; deploy targets re-pointed at credentials you issued.	Builds keep passing because they still deploy with the old developer's personal token — until it expires.
Cloud console	The root/owner account on your email with billing on your card; the old developer reduced to a revocable role, then removed.	You have an admin user inside an account they own — they can still close the whole account.
Domain & DNS	Registrant transfer of the domain to your registrar account; the DNS zone hosted under your account.	The domain is the business. If only one item on this table gets done, make it this one.
Database	Hosting account in your name, superuser credentials you set yourself, and a backup you have personally restored once.	Backups that were never tested, or that write to storage the old developer owns.
Error tracking & logs	Project ownership transferred; alert emails re-pointed at your inbox.	Errors have been silently emailing a departed person for months.
Analytics	Property ownership (not just viewer access) under your account.	Years of traffic history stranded in an account you cannot access.
App store accounts	Apps transferred to your own Apple Developer and Google Play accounts.	The app listing — reviews, install base and all — lives in the freelancer's personal account.

Do this stage while the old developer is still cooperative and still being paid. Goodwill is an expiring asset; account transfers that take five minutes today can take months once the person has moved on.

Stage 2 — secret rotation

Rotate every secret the day they lose access

This is not an accusation — it is hygiene. Every credential the old developer used now exists on hardware you don't control: laptops, old .env files, shell history, password managers. Rotation is also the only remedy for secrets committed to git at any point: deleting them from the current code does not delete them from history.

Secret	Why it must rotate
Third-party API keys (payments, email, maps, LLM providers)	Anyone holding an old key can run up charges on your bill or, worse, read the customer data those APIs expose. Payment provider keys are the priority — rotate live keys before test keys.
Database passwords & connection strings	A connection string is direct read/write access to production data, bypassing the application and every rule in it. Rotate the password and restrict network access to known hosts at the same time.
Deploy keys & SSH keys	Removing someone's account does not remove their key from `authorized_keys` on the server or from the repo's deploy-key list. Audit both lists and remove anything you did not issue.
OAuth client secrets	A leaked client secret lets someone mint tokens that impersonate your application to Google, Apple or any other identity provider — invisible in your own logs.
Webhook signing secrets	Whoever holds the signing secret can forge events your app trusts — a fabricated "payment succeeded" webhook is the classic abuse. Rotate at the provider and update your app in the same deploy.
Cloud IAM users, tokens & service accounts	Long-lived access keys survive the person leaving. List every IAM user and access key, delete the ones tied to the old developer, and check audit logs for keys you cannot attribute.
CI/CD environment variables	Pipelines cache copies of many of the secrets above. Rotate the sources first, then update the pipeline copies — otherwise the next build quietly deploys with dead credentials.

Sequence matters: revoke account access first, rotate the same day, then scan git history for hardcoded secrets (tools like gitleaks or trufflehog automate this) so you know which keys were exposed the longest.

Stage 3 — orientation pass

Prove you can build, run and ship it without them

A repository you cannot turn into a running application is an archive, not a handover. The orientation pass answers one question: could a competent engineer who has never seen this project get it live from what exists today? Run it on a clean machine — a fresh VM or container, not the laptop that already has everything installed — because the clean machine is where the undocumented steps surface.

The final step is the one most people skip: map the deployed version against the repository HEAD. Diff what is actually running in production against the latest commit. Hotfixes applied directly on the server and never committed are extremely common at the end of a strained engagement, and they vanish on your first deploy if you don't capture them now.

Run in this order

README & docs audit — can a stranger set up from the docs alone? Note every gap as you hit it
Clean-machine install — fresh clone, dependency install from the lockfile, on a machine with nothing pre-installed
Environment reproduction — inventory every environment variable the app actually reads vs what .env.example admits to
Run the test suite — does one exist, does it pass, and does it cover the paths that make you money?
Deployed version vs repo HEAD — diff production against the latest commit; commit any server-side hotfixes you find
One full deploy — ship a trivial change end-to-end to prove the pipeline works under your credentials

Stage 4 — licence & dependency audit

Find the legal and financial surprises before they find you

Inherited code carries inherited obligations. An hour with a licence scanner now is cheaper than discovering any of these after launch:

Copyleft surprises — a GPL library statically linked into proprietary code, or an AGPL dependency in a SaaS backend, can oblige you to publish source you consider a trade secret. Run a scanner (licence-checker for Node, pip-licenses for Python, or an SCA tool) over the full dependency tree, not just direct dependencies.
Unlicensed snippets — code pasted from tutorials or forums with no licence, and purchased themes or plugins bought under a single-site licence tied to the old developer's account, are both quietly common. Large verbatim blocks with a different coding style are the tell.
Expired or personal API plans — services running on the old developer's personal free tier, or billed to their card, fail exactly when they stop caring. Cross-reference every external hostname in the config against an account you own and pay for.
Abandoned dependencies — packages years out of date or unmaintained upstream. Run the ecosystem's audit command (npm audit, pip-audit, composer audit) and triage known vulnerabilities by exploitability, not raw count.
Missing lockfiles — no committed lockfile means every install may resolve different versions than production runs. Generate one from the known-good environment before touching anything else.

Stage 5 — documentation debt

Write it down in week one, while ignorance is still useful

Week one is the only time you experience the project as an outsider — every confusing thing you hit is a documentation gap the next person will hit too. After a month you will have internalised the quirks and stopped seeing them. Capture them now, cheaply, in plain text files in the repository where they cannot be lost with an account.

None of this needs to be polished. A dated bullet list beats a beautiful wiki that never gets written.

The week-one write-downs

One-page architecture sketch — the services, what talks to what, and where state lives
Deploy runbook — the exact commands from commit to production, including the embarrassing manual steps
Environment variable inventory — every variable, what it does, where its value lives
Third-party service register — each external service, which account owns it, which card pays for it, when it renews
Known bugs & quirks list — everything the old developer said "oh, that's normal" about
Decision log — start one now; entry #1 is "inherited codebase, state as found"

When it goes wrong

When the handover is hostile — or there is no one to hand over

Everything above assumes a cooperating counterpart. If the old developer has gone silent, is withholding access, or is demanding unagreed payment for the handover, change footing:

Check the contract first. If it assigns IP to you, a short written demand citing the clause and setting a deadline resolves most standoffs. No contract, or one that is silent on IP, weakens your position — take advice before making threats you can't back.
Use the platform if there is one. If the work ran through a marketplace such as Upwork or Fiverr, open a dispute through the platform. Marketplace escrow and dispute processes are genuinely effective levers while money or the freelancer's account standing is at stake — it is one of the things those platforms do well.
Secure what you already control, immediately. Snapshot the production server, export the database, download any deployed build artefacts, and back up the DNS zone. Running code can usually be recovered from a server you control even with no repository access at all — you lose the git history, not the product.
Set a rebuild threshold. Decide early how long you will chase access before treating the recovered artefacts as the starting point. A recovered-then-rebuilt codebase with a fresh history is often cheaper than months of pursuit.

We've written a dedicated guide for the abandonment case — what to do when a freelancer abandons your project — and if you want a team to run the recovery, the takeover and the stabilisation as one engagement, that is exactly what our app rescue service is for.

Questions & answers

Developer handover — FAQ

What should I rotate the day the old developer loses access?

Every credential they ever had or could have copied: third-party API keys, database passwords and connection strings, deploy and SSH keys, OAuth client secrets, webhook signing secrets and any cloud access tokens. Treat everything in the.env file and CI/CD settings as compromised — not because the developer is malicious, but because copies now exist on hardware you don't control. Rotation is the only fix; removing a secret from the repository does not remove it from git history.

Is collaborator access enough, or do I need repository ownership?

You need ownership. A collaborator can be removed by the owner at any time, and the owner keeps the repository if the relationship sours. Ask for a full ownership transfer into a GitHub or GitLab organisation that you own — on GitHub that is Settings, then Danger Zone, then Transfer ownership. A transfer preserves the full commit history, issues and releases, and makes you the party who grants access from then on.

What if the previous developer refuses to hand over the code?

Start with your contract: if it assigns IP to you, a written demand citing that clause resolves most cases. If the work went through a marketplace such as Upwork or Fiverr, use the platform's dispute process — it typically carries real weight while funds or the account are at stake. In parallel, secure what you already control: snapshot the production server, export the database and save any deployed build, because running code can usually be recovered from a server even without repository access. If none of that works, rebuilding from the recovered artefacts is often faster and cheaper than a legal fight.

How long does a proper codebase handover take?

For a typical small product, plan one to two weeks of focused work: a day or two for access transfer and secret rotation, two to three days for the orientation pass — clean install, environment reproduction, test run and mapping the deployed version against the repository — and the remainder for the licence audit and week-one documentation. A live handover call with the outgoing developer compresses this dramatically; even one hour of walkthrough is worth days of reverse-engineering.