Pantheon.io Workflow Explained

Intro

This tutorial assumes that you understand the basics of GIT and WordPress File Structure^[1][2]

Pantheon.io^[3] is a webhost that specializes in WordPress and Drupal hosting, but also allows for GIT version control. It is a happy medium between good hosts like Siteground or WPEngine that are excellent hosts, but don’t allow you to easily clone the site with GIT, and the big enterprise solutions like AWS that can only be worked with very advanced users. Pantheon is excellent and easy to use, but you do need to take a bit of time to understand their workflow. When you understand it completely you can work with it in the correct way and save yourself some headaches (or panic attacks) in the future. At its core you need to understand 2 main concepts:

1. Your site has 3 environments
2. Your site has 3 types of Data

First you will want to understand the 3 types of Data, and make sure that you understand which of these 3 buckets each part of your site falls in to.

3 Data Types

It is important to understand these three Data types because you will be moving each of the three independently in different directions. Either Upstream or Downstream between your environments. You need to know which direction each type of data should flow, and therefore need to know exactly what is included in each of these data types. The Files datatype had me confused at first because I tend to think of files as site files, like code. But when Pantheon refers to Files they are talking about media uploads like images. Make sure you remember this. Code and Database are straightforward. If you have worked with WordPress in the past you should know what is included in the Database, this is not unique to Pantheon. In short:

• Code is all the files under GIT control
• Files + Database is the site content and is NOT GIT controlled.

You will be pushing these three types of data around your three environments:

3 Environments

The Dev site is where you will be able to GIT Clone, and Push your Code. From there you will push the code upstream to take effect on the other environments. You can also periodically pull down the Files and Database from the Test and Live environments so the Dev site will look the same. I have some notes about Pushing code changes but first lets take a look at a data flow diagram so that this is all very clear:

Data Flow

There are some things to take note of here. We can see that Code is flowing upstream in this diagram. You should note that Code can ONLY flow upstream, it is not possible to pull code changes back down. In fact making code changes on the Test and Live environments has been disabled. If you go to the Test site Dashboard>Plugins you will see that the option to install new plugins from the Dashboard has been removed. The Code flow is one way only.

Files + Database can go both ways. I can copy Files or Database in either direction independently. Obviously you are generally going to have the files and Database flowing downstream though. Why is that? If I am a developer and I am working on the Dev environment, doing my thing, making big changes; while I am doing that, database changes are happening on the live site. Orders are being placed, blog posts written, page content changed, photos uploaded etc. All of those things are Files + Database changes. If you take the Files and Database from the Dev site and Push it upstream, you will overwrite all of that important content. Remember that you CAN do this, and sometimes you must, but in general the Files and Database will be flowing downstream.

Ok, this is the part where we go into some specific tips, tricks and examples, so please make sure you completely understand what I have covered so far before you move on.

Undoing Changes and Commits

It happens all the time, you commit a change to try something out, it doesn’t work and now we want to take a step back; how do we do that? While Pantheon gives you more options to control your site with GIT than anyone else, it is not without restrictions. For example you cannot use the GIT Reset function. What are the consequences of this? First lets briefly cover the difference between GIT Reset and GIT Revert.

Revert vs Reset

Let us say that I have 5 commits in a row:

So we have committed these 5 changes. Now if I Revert Commit #3, I will be undoing JUST that commit. I will be removing Yoast SEO, but I will still be on WordPress 5.0 and have Revolution Slider installed. However if I Reset to Commit #3, I am resetting the head of my branch to that location and undoing ALL of the changes that happened after that.

You cannot Reset a Pantheon repo. If you do that on your local copy and try to push it to Pantheon you will be rejected and told that you are behind.

For example if we have a string of commits here on the local repo and I want to go back to my fresh install of Jupiter 6 theme as shown here:

I can do that locally, but when you then try to push that change to the remote pantheon repo you will get the following error message:

So how do we undo changes once they have been committed to our Dev site? The answer is Revert. When you Revert a commit you do not actually remove it from the tree. You are adding another commit, which means you will not be behind the remote repo and you will be able to safely push that change:

Here we have reverted the last commit, then we push our repo to the remote repository and on the Pantheon website we will see our changes being synced:

And then we can check the Pantheon log and see that our changes have been pushed successfully:

SFTP Mode vs GIT Mode

One of the nice features of the Pantheon Dev Environment is that you do not have to push all of your changes through GIT. You can connect via SFTP and make changes that way. Any changes that you make in SFTP mode will be consolidated into 1 commit when you switch back to GIT mode, which you can then pull down to your local repo. One of the nice things about working in SFTP mode is that you can install plugins directly through the WordPress dashboard. If you try to do this while you are in GIT mode the installation will fail because the sites file write permissions have been locked and cannot be written to while in GIT mode. You will be prompted for FTP credentials:

Spoiler Alert: nothing you put in here will work.

You will also be unable to update plugins that are already installed, or register plugins with confirmation codes. To do these things you will need to be in SFTP mode. This is the real trick that the other hosts have not figured out, the switching back and forth between these two modes. Pantheon does not do a good job of explaining this in their docs however.

So just remember, if you are in the WordPress dashboard trying to install plugins, or register them, or update themes and its not working, you are probably in GIT mode when you should be in SFTP.

Ignoring Update Nags

One of the things that you will run into with Pantheon is the constant update nags, trying to get you to commit WordPress updates. They look like this:

Do not accept these commits. Updating WordPress to the latest version immediately after it has been released is one of the all time greatest ways to break your site. You need to give your theme and plugin developers time to make compatibility updates and then install WordPress updates manually. The only people who would want to do this are people running very simple blogs with few plugins. If you are running an e-commerce site blindly applying these updates is a BIG NO NO.

Just remember, you can keep applying your own code commits and doing what you need to do while completely ignoring these “nags” (That is what the Pantheon customer service guys call them).

Bonus Question

Extra points now if you get this correct. Here is the scenario:

“You have updated from WordPress 4.9 to 5.0 on the Dev site using a GIT commit. And then you committed those changes to the Test site. Oops, now you realized your mistake. None of your plugins or your version of WooCommerce are compatible with this massive WordPress update. We need to undo this change!”

How do you go about this?

If you answered “Use a revert to this commit on the Dev site and then push that change to the Test site” you are only half correct. In this case the big update to WordPress also made several changes to your database. To roll back those changes you will need to do more than just revert the code, you need to load a backup of your database or copy the database from the Live environment as well.

That is a bit of a trick question but these are the things you need to think about.

Conclusion

It seems like a lot to manage but once you have worked with it for a bit the workflow becomes very intuitive and convenient. You have the ability to track changes with GIT and work with a group, while at the same time getting a nice interface for less tech-savvy users. There are some other quirks that you will have to take care of if you are starting up with Pantheon. For example:

• There is no .htaccess files with Pantheon. So any re-directs need to be handled manually the wp-config.php file or by using a WordPress plugin.
• The standard WordPress email function does not work with Pantheon. You need to set up an SMTP server and connect to it. I prefer Mailgun^[4], and WordPress has a slick plugin^[5] that integrates with them seamlessly.
• If you are migrating over an older site, you need to double check which version of PHP your Pantheon server is running. Odds are that your old site is running on an older version and you will be wondering why so many things are broken. You can force Pantheon to run an older version of PHP^[6].

References

1. ^{^} basics of GIT
2. ^{^} WordPress File Structure
3. ^{^} Pantheon.io (pantheon.io)
4. ^{^} Mailgun (www.mailgun.com)
5. ^{^} slick plugin (wordpress.org)
6. ^{^} You can force Pantheon to run an older version of PHP (pantheon.io)