There comes a time within the course of project events, that we must create distinct, equivalent environments to test new features and bug fixes so that we are not constantly merging untested work into main line development. Enter Pantheon Multidev.
Outline
- What is Multidev?
- Event triggers for creating, updating, and tearing down Multidev environments
- Triggered processes, by event
- Complete picture
What is a Pantheon Multidev Environment?
Source: https://pantheon.io/docs/multidev
Pantheon’s Multidev feature permits the on-demand creation of separate environments based on a Git branch. A common feature-based workflow scenario is having your master branch deployed to your dev environment, and then having feature/bug branches stemming from master be used to create Multidev environments to test that work prior to it being merged into master, so you can QA the work before master trickles up to production.
Event triggers
If we think about a typical project workflow through a provider like GitHub, Bitbucket, or Gitlab, a developer will:
- Branch off of the main branch of development to do their work and then…
- Submit a pull request to be reviewed and…
- Eventually be merged back into the main line.
Multidev fits nicely into this workflow, and the creation, update, and teardown events of a Multidev lifecycle can be mapped onto the events of a pull request lifecycle.
Before diving into how we map our events onto the Multidev workflow, there are a couple things to keep in mind:
- The branch, used to create the Multidev environment, must exist in the Panthon repository before the Multidev environment is created.
- The name of the Multidev environment will be the same name as the branch which it is based on.
- A branch used to create a Multidev environment must follow the naming conventions:
Branch names can contain any ASCII letter and number (a through z, 0 through 9) and hyphen (dash). The branch name must start with a letter or number. Currently, the maximum length is 11 characters and environments cannot be created with the following reserved names: master, settings, team, support, debug, multidev, files, tags, and billing.
From: https://pantheon.io/docs/multidev-faq#what-are-the-naming-conventions-for-branches .
Note: Going into the events, we assume that in all runner environments that the code available is a git reference being a merge between the branches merging from and to.
Create Multidev when a pull request is opened
When a pull request is first opened, we need to create a Multidev environment to present the work done. Considering that the name of the branch may be named in a way which conflicts with Multidev branch naming requirements (see above), instead of pushing the branch as-is to the Pantheon repository, it is best to setup a tracking branch with a name based on the pull request number. For example, if you opened pull request number 15 for branchfeature/ABC-123-new-hero-image-section into the main branch, then you would push the PR branch up to the Pantheon repository as pr-15.
Assuming you’ve setup a remote of pantheon to point at the Pantheon repository, and you have stored the pull request number in the shell variable pr_number:
git push pantheon HEAD:refs/heads/pr-$pr_number --force --quiet
Force push is required in case that branch already exists, we want to ensure that the code present is updated to reflect the latest version of the code in this particular pull request (e.g. you can open and close a pull request multiple times, but the number remains the same).
After the code has been pushed, you can use Terminus to create the Multidev environment:
terminus multidev:create --no-interaction --quiet --yes project.dev pr-$pr_number
After that completes, you’ll have an environment waiting for you based off of the development environment. If you want to base the Multidev environment initially on the production or test environments, update project.dev above accordingly.
Update Multidev when a pull request’s code is updated
When a branch, that is the subject of an open pull request, is updated (e.g. has more code pushed to it) then the companion Multidev environment should be updated as well. This is accomplished by force pushing the code like before when the pull request was first opened:
git push pantheon HEAD:refs/heads/pr-$pr_number --force --quiet
You should have Quicksilver hooks in place so that you can run any database updates or import configuration when a Multidev environment receives code changes. An example of this is available in Pantheon’s GitHub https://github.com/pantheon-systems/quicksilver-examples/tree/main/drush_config_import .
Note: If for a Drupal project and your version of Drush supports it, we suggest substituting the various Drush commands in the example with a singular usage of drush deploy -y --no-interaction.
Destroy Multidev after the pull request has been closed
When a pull request is finally closed (whether that be through merging or explicitly closing) you should use Terminus to clean up the Multidev environment, as it has served its purpose. To do so:
terminus multidev:delete --delete-branch --no-interaction --quiet --yes project.pr-$pr_number
Complete picture, tying it all together
We’ve gone over the basics of coupling Pantheon’s Multidev feature to your project’s code contribution workflow. Now, go out there and take full advantage of this awesome feature from Pantheon, and go into your QA process with more confidence than ever!