For an agency or founder handing over a codebase: what to check so the next owner can run it

Four questions a successor will ask in week one

When an agency finishes a project, a founder sells a product or a lead developer leaves, the next owner asks four things, usually in this order. Can I run it? Is it carrying known problems I should hear about now? Is anything in it that should not be? Has anyone besides the author read the latest work? You can answer them yourself before you hand over, and the answers are worth more than any statement that the code is clean. Treat the handover as something the receiver could try without you, and keep a record of what you checked and when.

• Run it: follow only the README on a clean machine.
• Known problems: run your dependency scanner and keep the result.
• Secrets: look for committed credentials, in files and in history.
• Second reader: have someone independent look at the latest changes.

Check each one in turn

For the first, GitHub's guidance is that a README should say what the project does, how to get started, where to get help and who maintains it. Follow it, and only it, on a clean environment, and fix each place you improvised. For the second, a scanner or Dependabot alerts list known advisories for the packages you use; GitHub says its alerts will not catch every issue and that new vulnerabilities can take time to appear, so keep the date of the scan. For the third, if you find a credential, revoke or rotate it first and treat the repository cleanup as housekeeping. For the fourth, the standard worth using is whether the change improves overall code health, not whether it is perfect.

• Keep the scanner output, the cold-start record and the review notes together in the handover pack.
• Do not describe a clean scan as a statement that the code is secure.

Decide what to fix and what to disclose

Some findings you fix before handover, some you hand over with a plain list, and some are decisions for the new owner. A major framework upgrade, a package with no fixed version and a risky area with thin tests all belong on a list with the reason, not hidden. A short honest list serves the successor better than a clean-looking handover that falls apart in the first month, and it protects you from a later argument about what was known. Where you hand over work for a client, state what was reviewed and what was not.

• Write a one-page known issues list beside the README.
• Say who holds each account, key and domain, so ownership is not left to chance.

Bounded help, if you want it

Four small jobs map to these questions. A README rewrite proven by a cold start on a clean machine has a published test price of £295. Clearing the fixable findings from one scanner in one repository starts from £495 after a quote. Removing a committed secret from one repository, with a rotation checklist you complete, is £395. A written review of up to five pull requests is £495. All prices are untested hypotheses, nothing is charged before sign-off on a fixed job, and we have not delivered these jobs for a client. Nothing here is a security audit, a certification or an approval that code is safe to run. Send the stack, the platform and what you are handing over, never code, keys or customer data.