Inheriting a Codebase From Another Agency: A Checklist

Switching development vendors goes wrong in a predictable order. Teams review the code first, discover the repository sits in the old agency’s GitHub organisation, and then spend three weeks asking for access they should have had on day one. Do it the other way round. Get every account into your name, rotate every secret, and only then start judging the code.

This is the order that works for a typical web product with a mobile app, whether you are leaving an agency or a freelancer.

Inventory what exists before you ask for anything

You cannot request access to things you don’t know about. Before the first call with the outgoing team, write down every place your product lives. If you can’t answer a line yourself, put it on the list of questions for them.

• Source repositories, including any private forks and the CI configuration
• Cloud accounts (hosting, database, storage, email sending) and who receives the invoices
• Apple and Google developer accounts, and whose legal name is on each
• Domain registrar, DNS provider and TLS certificates
• Third-party services: analytics, payments, error tracking, push notifications, maps
• Any scheduled jobs or webhooks that call the product from outside

The billing question is the quickest test of ownership. Whoever pays for an account usually controls it, and an invoice addressed to the agency tells you the account is theirs.

Move the repository with its history

A zip of the latest code loses the history, and the history is how a new team learns why things are the way they are. Move the repository itself.

If the old vendor has a GitHub repository and you have an organisation, a transfer is the cleanest route. GitHub’s documentation says issues, pull requests, the wiki, webhooks, deploy keys and Actions secrets stay with the repository, and links to the old location redirect. The person transferring needs admin rights on the repository (or owner rights in the organisation that holds it), and a transfer to a personal account expires after a day if nobody accepts. Two details matter for handovers. Read-only collaborators don’t carry over when a repository moves from an organisation to a personal account, and the new team will need to be re-invited. And if you later create a repository at the old location, the redirects are permanently deleted.

If a transfer isn’t possible, take a full mirror and push it somewhere you own:

git clone --mirror git@github.com:old-agency/your-product.git
cd your-product.git
git remote set-url --push origin git@github.com:your-org/your-product.git
git push --mirror

Then check that the branch and tag counts match on both sides. A mirror carries every ref, so you also get the stale branches. Those are worth reading, because abandoned branches often show what the previous team tried and dropped.

One more thing to look at before you celebrate: who actually wrote the code.

git shortlog -sne --all | head -20

If half the commits come from addresses you’ve never heard of, the old agency used subcontractors. That’s a question for your IP position, which is covered in who owns the code when you hire developers. Check that the contract required valid assignments from every person on the list.

Cloud accounts: invite first, then remove

For cloud infrastructure the safe pattern is to create your own account or organisation, add the old team as temporary members, and migrate the resources with them watching. Moving the other way (you as a guest in their account) leaves them with the root user.

On AWS, the IAM best practices say to protect root credentials carefully, require MFA, prefer temporary credentials from roles over long-lived access keys, and regularly remove unused users, roles and credentials. The same page says to update access keys when someone leaves, and to use last-accessed information to remove them safely. That list is effectively your offboarding checklist for the outgoing team. Make sure the root user email and MFA device belong to someone at your company, and not to an alias on the agency’s domain.

Mobile apps take the longest, so start them first

If the product has iOS or Android apps, begin these transfers on day one, because they have prerequisites that can’t be hurried.

For iOS, Apple’s app transfer process must be started by the Account Holder of the sending team and accepted by the Account Holder of the receiving team. Before the transfer, the sender has to remove TestFlight builds and testers and clear Xcode Cloud data. Apps with auto-renewable subscriptions need an app-specific shared secret handed to the recipient first. Reviews, ratings, the bundle ID and continued availability stay with the app, but some things don’t survive. The Apple Pay merchant ID isn’t transferred, so the new owner creates one when shipping an update. Push notifications switch to the recipient’s APNs certificates or keys, which means your servers need updating. And the sender keeps access to pre-transfer sales data while the recipient only sees sales from after the transfer, so ask the old team to export their reports before the switch.

For Android, Google’s transfer process requires that you can sign in to the original account, that the target account’s registration is complete, and that every app being moved complies with Play policy. A policy violation on any app in the original account, or an unfinished APK translation project, can block the request. Apps with paid or in-app products need an active payments profile on the target account. Decide up front whether to rotate the upload key or request a new app signing key for new installs. Test groups and integrated-service permissions don’t transfer, so recreate them.

A tempting shortcut is to upload the app again under your own account. That creates a new listing with no reviews, no install base and no update path for existing users. Transfer it.

Rotate everything

Assume every secret the old team could read is now exposed, even when they’ve been scrupulous. You can’t prove a key was never copied to a laptop.

Scan the history for credentials that were committed by accident:

gitleaks detect --source . --log-opts="--all"

Anything it finds gets rotated, not just deleted from the latest commit, because it stays in history. Then work through the list: database passwords, API keys for payment and email providers, signing keys, CI tokens, SSH deploy keys and webhook secrets. Issue new ones to the new team through a password manager or your cloud’s secret store. The environment variable names from the old team are useful documentation; the values are not worth keeping.

Audit the code after the keys are yours

Now the code review is safe to do, and the new team can do it properly. Ask for a written audit rather than verbal impressions: does it build from a clean checkout, what do the tests cover, which dependencies are out of date, and what does a deploy actually involve. Technical due diligence covers how to structure that assessment.

A good handover also produces a short document, written by the outgoing team, with the architecture, the deploy steps and the known problems. Write the request into the offboarding agreement before the old team’s last invoice is paid. After that you’ve lost your leverage.

Test the handover with real work

Documentation looks complete until someone tries to use it. Give the new team one small, real ticket, with a fixed scope and a fixed fee, and watch what they have to ask the old team. Every question is a gap in the handover. The paid trial project approach works for the same reason when you vet a new vendor, and it doubles as a handover test.

If you’re still choosing the replacement, how to hire a software development agency covers what to ask them, and the first 30 days of developer onboarding is a reasonable plan for what happens after access is sorted. If you want a second opinion on a handover plan, CoderCops services is one place to start.

The rule underneath all of this is short. Don’t let any account that matters stay in someone else’s name, and don’t call the handover finished until a new developer has shipped a change using only what the old team left behind.