Changing who looks after your Craft CMS site is more complicated than it might appear. Craft installations can be deeply customised, with knowledge about how the site works sitting in the heads of the people who built it. A poor handover leaves a new developer struggling with undocumented code, a business owner without proper access to their own site, and the kind of uncertainty that makes everything more expensive.
Done properly, a Craft CMS handover gives the new developer a clear understanding of what they are taking on, and gives you confidence that you have not inadvertently handed over control of your most important digital asset.
The access checklist
Before or at the point of handover, you should have direct access to the following, independent of any agency or developer relationship:
- Craft CMS control panel. Your own admin-level login, at an email address you control. Not your agency's email address, and not an account that requires your agency to reset. If you need someone to set this up, ask for it explicitly before the relationship ends.
- The Git repository. The Craft codebase should be in version control. If your agency hosted it in their own GitHub, GitLab, or Bitbucket organisation, you need a copy transferred to a repository you own before that access disappears. Transferring repository ownership is straightforward but requires the agency to initiate it.
- Hosting access. SSH credentials, SFTP access, or control panel login for the server that hosts the site. Your hosting provider should be able to supply these independently of the agency.
- Database access and a current backup. The database contains all your content, orders, user accounts, and configuration. A complete, verified backup should be in your possession at handover.
- Domain registration. Confirm that the domain is registered in your name, at an email address you control. Agencies that register domains on behalf of clients sometimes do so in their own company's name, which causes significant problems when the relationship ends.
- Third-party service credentials. Any external services the site uses, including payment gateways, email sending services, analytics platforms, CDN accounts, and API keys, should be in accounts you own or at minimum accessible to you.
What to request from the outgoing developer
In addition to access, there is information that will make the handover considerably smoother for whoever takes over:
- A list of plugins installed and their versions. This can also be obtained from the Craft CP or from the composer.json file, but having it documented explicitly is useful.
- Notes on any custom modules or plugins. Bespoke code that was written specifically for your site is not documented anywhere publicly. A brief explanation of what custom code exists and what it does is genuinely valuable.
- Notes on any known issues or quirks. Every site has things that work in non-obvious ways. Things that the outgoing developer knows without thinking about but that are not obvious from reading the code.
- Deployment process documentation. How does code get from development to production? Is there a staging environment? Are there any manual steps that need to happen at deployment?
Red flags to watch for
A few warning signs that a handover may not go smoothly:
- The agency is reluctant to provide access to the Git repository or transfer it to your ownership
- There is no version control at all, just files on a server
- The agency holds the domain registration and is unresponsive about transferring it
- There are no backups, or the last backup was months ago
- The site uses agency-owned API keys or third-party accounts that cannot easily be transferred
These situations can be resolved, but they take time and occasionally require escalation. Identifying them before the relationship ends completely is considerably easier than resolving them afterwards.
What a new developer should do at handover
A specialist taking over a Craft CMS site should spend time properly understanding what exists before making any changes. The first priority should be a thorough audit: which version of Craft is running, what plugins are installed and whether they are current, what custom code exists, whether there are any immediate security or stability concerns, and what the dependencies look like for hosting, third-party services, and the deployment process.
Rushing to start development work before this understanding is in place is how new problems get introduced while resolving existing ones.
If you are planning a Craft CMS handover and want guidance on how to manage it properly, or if you are the business owner on the receiving end of a handover that has not gone smoothly, get in touch and Karl will help you work through it.