Code deploys, content does not

Who this is for. Everyone on a project who builds something in the admin and expects it to go live with the next push. Afterwards you can list, for any change, which part a push carries and which part must be created by hand, and release them in the right order.

Teams expect a deploy to carry the new layout they built, and it does not. A layout is a record that points at a template file: the push carries the file, and the record stays wherever it was created. The same is true of nearly everything an editor or an administrator sets up.

What travels with a push, and what does not

A few things are in neither. An environment's mode, its connections, its setting overrides and its search index settings, including the facets mapping template, are files in the environment's folder on the server, outside the repository, set per environment (where configuration lives, search and environments).

Within one site: records point at code

The environments of a site share their database, so between staging and production there is nothing to move: a record created on either is on both (what environments share). The risk runs the other way. Records point at code by path, and the code differs between environments until the release:

• A layout points at a template file by its path. Deploy the template to every environment that uses the layout: without it, a page with that layout fails there with an error, and a component with that layout renders blank, with no error.
• A job action can name a template file for its body or its email, and fails when it runs if the file is not deployed.
• Renaming or moving a template that a record points at breaks every record that uses it, on every environment the rename reaches. Point the records at the new path in the same release.

So the order of a release is code first, records second. Release the template (an unused template harms nothing), then create the layout and use it. Creating the layout first offers it to editors on production before its template exists there.

Between platform instances: records must be moved

A copy of the site on a development platform has a database of its own. Moving work from there to production means recreating or importing every record the work depends on, and three things change on the way:

• Ids differ. A record created again gets a new id, so a template that refers to a record by id breaks. Find global components by identifier, menus by name and pages by URL, never by id.
• Some things do not export. The admin's export carries layouts, input types, custom fields, settings and jobs, not forms, menus, site data, redirects or content (Moving configuration between sites).
• References inside records point at the old ids, such as a job narrowed to one form or a component that lists the layouts it accepts. Check each one after the move.

Write the records into the release

For every change that needs records, list them in the pull request that carries the code: each layout with its template path and areas, each input type, job, form, setting and site data key, each redirect. Whoever releases then knows what to create and in which order, and the list is the record of what changed in the database, which git cannot keep.