All the steps need to deploy a new version of Planet 4

Our main orchestration repository for triggering deployment pipelines is planet4-base-fork. But before we make any change there we need first to prepare the application repositories.

Application Repositories

The only change that it's actually needed is to tag the repositories that have new code since the previous release.

So check master-theme and plugin-gutenberg-blocks. If they have commits on master branch since last tag (probably both have) the you need to create a new tag. You can do that directly from Github interface or locally as shown below.

git tag -a vX.XX -m "vX.XX"
git push --tags

Note the -a flag above. We always use annotated tags.

Base repository

planet4-base-fork repository has two main branches:

  • develop: Controls the develop pipeline and what is being deployed on develop sites.

  • master: Controls the release pipeline and what is being deployed first on stagning and then on production sites.

So every time there is a new Planet 4 version to be released there it's not required to also update the develop sites. But keep in mind that any code changes (eg, tests) are first merged to develop branch, so you may have to merge it to master.

All you have to do is edit composer.json, update the versions of the plugins/themes as needed and the version of composer itself (example).

🧙 If you include in the subject line of your git commit message the string[HOLD] then, even if all the tests are successful, it will require a manual approval for deploying from staging to production.

Trigger Release

If you updated the develop branch, its pipeline will be "on hold". You do not need to trigger that now, because it would delay the production release. You can approve it later.

Check CI for the release pipeline. When all tests pass it will stay "On Hold" waiting for a manual approval.

Approve that and it will trigger the release pipeline on all websites. This is an overview of a release pipeline for a website:

There is a "hold-promote" job there that controls whether the pipeline will continue deploying on production. This job will be approved automatically (from the "promote" job) if all tests pass successfully.

You will only need to manual approve that in two cases:

  1. You added a [HOLD] on your commit message on base-fork. This will require manual approval on all websites.

  2. Visual Regression tests failed on a specific website. You can use this spreadsheet and run: Planet 4 > Update CircleCI. This will update the CircleCI sheet using CircleCI’s API. You can then open just the ones that are on hold. Alternatively you can keep an eye on the #p4-activity-ci channel.

  3. You can then check the tests report to confirm that the visual differences are acceptable.

🐞 If you discover a bug during the Regression Tests report, you can open a ticket.

NRO specific cases

  • If you spot important significant visual differences on websites with customized child themes you should inform them and don't approve the deployment to production. They have CI access to approve it when ready. This includes: GPCH, GPNL, GPLX and all GPNORDIC websites.

  • Korea, Hongkong, Taiwan are also heavily customized through their child themes and require extra attention because they are still not switched to Gutenberg.


In some (hopefully rare) cases you may want to rollback to a previous release. For instance, if there is a major bug in production and you know that this is a regression from the latest release. To do so, you need to create a new tag with a rollback prefix (eg. rollback-v2.40 ). The version suffix doesn't play any role, is just a good practice to indicate witch version you are rolling back to.

This will trigger the rollback pipeline on each NRO, which will first deploy to staging and then wait for a manual approval to deploy production. This gives you the opportunity to do a final check on staging.