A guide is for software engineers and Contentful “admins”.
Scroll down to read why this weirdness is actually good.
Never fetch data from “master”!
Contentful’s environments do not work like Github branches!
Contentful uses the term “master”. This is NOT actually meant for “production” deployment!
The “master” environment is simply the public environment that the editor role users will be able to access. If you’re an admin, you may create multiple environments. Contentful lets you declare one of them as “master”. When an editor logs in, they will have logged in to the environment which you’ve designated as “master”. All other environments are like “private”, not accessible by an editor user.
“master” = staging
“master” is not a branch. It’s just a pointer to the branch which editors are currently editing
staging.yoursite.com will fetch from “staging” environment, which is actively being edited yoursite.com will fetch content from “production” environment, which is more stable
1) We never want to edit production directly. Therefore, “master” should never point to production.
2) Instead, always have a Production and Staging branch. Always point “master” to Staging, to edit Staging. Also have “ProductionRollback” branch, to restore from if something goes wrong.
Before deploying changes to uat/production, delete the Contentful “production” environment. We’ll still have “productionRollback” to restore from.
Then, make a new production from staging.
Deploy to UAT/Production (build, serve). See if everything is as expected.
🧪 🩺 👩⚕️ Test the site
If all is OK then delete productionRollback and make a new one from production.
If something is wrong, then restore production from productionRollback.
Edge cases
If there is no major issue, then “master” can always just point to “staging”, and “staging” never needs to be deleted and recreated. But of course there are edge cases.
Admins can always edit whatever environment they want. An “admin” user can select “production” in the top left dropdown, and edit some code there. Even though you can do this, do not! First, edit in “staging”, to test. This is required not for QA, but actually because if you edit content ONLY in production, then next time we push from staging->production, it will get lost. These environments are NOT like GIT branches. When we move content from staging->production, we will just delete production, and replace it with staging, not merge one into the other.
We may want to edit some production content (hotfix), while there is some new initiative being worked on in staging. This will usually be done by an admin anyway, so it’s ok. You can just go into production and change it. But be sure to edit staging first! See previous paragraph.
Maybe staging gets corrupted and we want to restore it from production? That’s ok. Just point “master” to “production” temporarily. Delete and recreate staging. Then point “master” to “staging” again to start editing it.
Backups
Each content item has its own version history, and we should always keep a “productionRollback” environment to restore the entire production from if something really goes wrong.
Why this weird process is actually good?
Because we want to make it easy for the editor. Editors are not technical people. They just want to edit the content. If we tell them “log in, and make changes, those changes will appear on staging”, they will understand that no problem. But if we allow them to choose which environment to edit (staging, production, feature), then they may accidentally edit the wrong one.
In other leading systems like Kontent.ai which have a clear and standard “feature->staging->production” workflow, the user logs in to “production” environment. Production is expected to be the source of truth. Staging seems to be used as a testing sandbox. The editor has to choose which environment to edit. That’s confusing and will require training and practice by each editor.
With Contentful’s system, plus the “hack” workflow described in this page, the process is simple. No training required. Editors can just edit the content and move on with their lives. We’ll never accidentally edit directly to production, unless we want to, but then only admins are allowed to do that, and must go out of their way to choose to edit production.