Skip to content
[ 05 ]Journal

How to Take Over a Codebase From Another Agency

Put every account in your name, rotate every secret and get the IP assigned in writing, then audit the code in week one. The full handover checklist.

All writing
How to Take Over a Codebase From Another Agency
Listen to this · AI voice11 min

By , Founder & CEOPublished

To take over a codebase from another agency, secure ownership before you touch the code: move the repository, cloud, domain and app-store accounts into your company's name, rotate every credential the old team ever held, and get the intellectual property assigned to you in writing. Then spend the first week reading and running what you have, so that every decision after that is made from a written audit rather than from the old agency's account of it.

Key takeaways
  • Ownership comes first. Accounts, credentials and a signed IP assignment are worth more than any amount of documentation, and they get harder to obtain the longer the relationship sours.
  • Rotate every secret, even with a friendly handover. Anyone who has held a key can still use it.
  • Audit before you build. In week one, rebuild the product from a clean checkout, deploy it to an environment you control, and write down what works.
  • An uncooperative agency is a legal and access problem, not a code problem. Most of what you need can be recovered from the accounts you own.
  • Expect weeks, not days. A cooperative handover with an audit takes roughly two to six weeks before a new team is shipping safely.

What has to be in your name before anything else?

Everything the product runs on: the code, the infrastructure, the domain, the app listings and the paid services. If any of these sit in the agency's account, the agency can switch your product off, whether by intent, by an unpaid invoice or by a former employee closing an account they forgot about.

Work through this list with the agency on a shared call and tick each item only when you have logged in yourself.

Source code and history. The repository should live in an organisation your company owns, with the agency added as collaborators. If it is in their organisation, ask them to transfer it rather than send a copy. On GitHub a transfer keeps the issues, pull requests, wiki and commit history, and links to the old location redirect automatically. Note that webhooks, secrets and deploy keys stay attached after a transfer, which is one more reason to rotate them. A zip file without the history is a red flag: the history is how a new team learns why the code is the way it is.

Credentials and secrets. Collect a list of every API key, database password, signing key and service account, with where each is stored. Then rotate all of them. The OWASP guidance is that secrets which are no longer needed, or may be compromised, should be revoked, and a departing vendor's knowledge of a key counts as both. Rotation also shows you which secrets the product really depends on.

Cloud hosting. AWS, Google Cloud, Azure, Vercel or whatever runs the product should be billed to your company and administered by an account you control. If it runs in the agency's own account, plan a migration; a shared login to someone else's cloud is not ownership.

Domain and DNS. The domain must be registered to your company, at a registrar where you hold the login. ICANN's guidance for domain holders explains the transfer code (also called an Auth-Code or EPP code) that the current registrar issues, and warns that changing the registrant can trigger a 60-day lock on moving to another registrar. Change one thing at a time and do the domain early.

App store listings. Apple and Google both have formal app transfer processes, and both require the app to move between developer accounts rather than simply changing the person who logs in. Apple's process is started by the sending Account Holder and accepted by the receiving one, and Apple advises backing up all app information first because the app leaves the old account. Google Play requires both accounts to be registered, active and in good standing. If the app was published under the agency's account, start this in week one; it is often the slowest item on the list.

Third-party services and contracts. Email delivery, payments, analytics, error tracking, maps, AI model providers and any licensed software. Each one needs an owner at your company, a billing card that is yours and, where there is a contract, a contract in your company's name.

Data and backups. Find out where production data lives, how it is backed up, and when a restore was last tested. Google's SRE book puts it well: nobody really wants backups, what they want are restores. Ask the agency to restore last night's backup into a fresh environment while you watch. If they cannot, you do not have a backup.

Environments, CI/CD and documentation. You want a list of every environment (development, staging, production), how code moves between them, the pipeline configuration, and whatever documentation exists, including the setup steps for a new developer's machine. Expect thin documentation; what matters is that the pipeline and environments sit in accounts you own.

Who owns the code, legally?

Not necessarily you, even if you paid for it. Under US copyright law, work produced by an outside contractor is only a "work made for hire" if it falls into one of nine statutory categories and both sides signed a written agreement saying so. The US Copyright Office's circular on the subject lists those categories, and software as such is not among them. In practice that means your rights in the code depend on an explicit assignment clause in the contract.

Read the contract for three things: a clause assigning all rights in the work product to your company, the trigger for that assignment (on creation is good; "upon final payment" leaves room for a dispute), and anything the agency has kept for itself, such as a reusable framework or library licensed back to you. If the clause is missing or conditional, get a short written assignment signed as part of the handover, and talk to a lawyer before you have a dispute rather than after. We cover what a development contract should say in our guide to choosing an agency.

How do you audit the code in the first week?

By trying to rebuild, run and deploy the product from nothing, and writing down what happens. A one-week audit is not a full review; it tells you whether the product exists in the form you were told, and what finishing will cost.

A practical week looks like this:

  1. Day one: build from a clean checkout. A new engineer, following only the written instructions, tries to get the product running locally. Every undocumented step they hit is a finding.
  2. Day two: deploy to an environment you own. Push the build through the pipeline, or by hand if there is no pipeline, into a staging environment in your account. This proves the product does not depend on a machine or account you cannot reach.
  3. Day three: walk the product against the scope. Take the original statement of work and click through every feature, with real-looking data. Mark each one working, partly working or missing.
  4. Day four: read for risk. Look at test coverage, dependency versions and known vulnerabilities, how authentication and payments are handled, and anything that touches personal data. Note the places nobody understands.
  5. Day five: write it down. One document: what works, what does not, what it will take to finish, and what you recommend keeping or replacing, with a price.

This is how we run our own rescue engagements. We read the code, run it end to end, and write down what works, what does not and what it will take to finish, with a price, and the client gets that document whether or not they hire us for the rest. Only then do we stabilise: a test suite, continuous integration and a repeatable deployment around what exists, before adding anything new. The audit decides what stays. Code that works and has a future is kept, and most takeovers keep more than they rebuild.

What if the old agency will not cooperate?

Secure what you control, recover the rest from the platforms, and keep a written record. Most stalled relationships end with an agency that is slow or unpaid rather than hostile, and a short written request with a deadline gets further than a long one.

  • Start with the accounts you already own. Any account billed to your company card, or registered to your company email, can usually be recovered through the provider's support process even if the agency holds the password.
  • Revoke access in a planned order. Once you hold admin rights, remove the agency's access and rotate secrets in the same session, so nothing is left half-open.
  • Use the platform processes. Registrars, app stores and code hosts have ownership and transfer processes that do not require the other party's goodwill indefinitely, though some do require their action. Your contract and proof of payment are what you will be asked for.
  • Settle what is genuinely owed. If there is an unpaid invoice, paying it in exchange for a signed assignment and a completed handover is often cheaper than the alternative.
  • Bring in a lawyer when the code or the IP is withheld. At that point the problem is contractual, and a letter from counsel tends to move faster than a new engineering team.

If the previous team is still around and willing, a gradual handover works well: the new team works from pull requests with written notes, and the old team answers questions for a few weeks.

What are the red flags during a handover?

The signs that something is being hidden, or never existed:

  • The code arrives as a zip file or a fresh repository with no history.
  • The only way to deploy is to ask the one developer who knows how.
  • Production runs in the agency's cloud account and they are reluctant to move it.
  • Secrets are hard-coded in the source, or shared in chat.
  • The agency cannot restore a backup on request.
  • Features on the invoice are missing from the product.
  • The contract assigns IP "upon final payment" and there is a dispute about payment.
  • Key libraries are the agency's own, licensed rather than assigned.

None of these is fatal alone. Three or more usually mean the audit will recommend replacing more than you hoped, and they are worth knowing before you sign a fixed price with anyone. Our guide to fixed price, time and materials and retainers explains why a takeover should be priced as a fixed-scope audit first: nobody can fix-price what they have not read.

How long does a codebase takeover take?

Roughly two to six weeks before a new team is shipping changes safely, if the old agency cooperates, and longer if it does not. The access and ownership work takes days to a few weeks, depending mostly on app store and cloud migrations. The audit takes about a week. Stabilising, meaning tests, a pipeline and fixes for whatever stops the product running in production, takes a few weeks more, depending on what the audit found.

Founders most want to skip the audit, because it feels like a week without progress. It is the week that tells you whether the next three months are a finish or a rebuild.

Sources

[ Next ]Keep reading