Deploying to WP Engine with GitHub Actions

Automated processes are now the norm in the programming industry. We use them for everything from retrieving or sending data to cleaning up caches. We also use them for deploying code reliably to our various environments.

WP Engine

WP Engine is a WordPress-focused hosting platform. It provides a simple and powerful interface for WordPress developers to do their work and keep the site backed up, safe, and manageable. Its environments each have their own git repository and you can also SSH into any environment to run commands, transfer files, and use the WordPress CLI tool.

When you checkout the WP Engine git repo you will notice it is sparse in files. You have a sitemap.xml file, the favicon, and a wp-content directory. This is simplified because WP Engine helps keep WordPress core separate and updated and fully secured.

Github

With our Microsoft partnership, we have been setting up more and more sites and applications on GitHub. In the past our focus has been on Bitbucket, first self-hosted then more recently cloud-hosted. Learning to use the various tools in GitHub is important to our ongoing operations. GitHub Actions are a big part of this for us developers.

I recently had the pleasure of working on the Dear Black Talent website which is built in WordPress, hosted at WP Engine, and running our development repo from GitHub. This site has seen several developers but none had a chance to clean up tech debt such as setting up automated processes. Until now. I have spent time both creating a script for local development and setting up our build and deploy processes.

Deployments

In this setup, we are primarily using the “Stage” and “Production” environments. To that end and to simplify build and deploy processes I created a “development” branch from the “main” branch and set it as the default. I defined a development process that includes branching from and doing Pull Requests back to the “development” branch while we are doing our main body of work. I set up a Github action so that pushing to this branch sets off the action that pushes that code to the stage environment.

Secondarily, I set up another action where pushes to the “main” branch kick off deployments to production. In each case the action spins up a virtual environment and runs through a set of commands to build the CSS and JS files then it moves on to an action built and provided by WP Engine that SSH’s over the files from Git to the target environment. This is incredibly easy to setup and is obviously directly supported by WP Engine.

The Actions

To create a GitHub action, you define a “.github/workflows” directory in the base of your repository. The workflows directory, I believe, is just the common convention and I don’t think you specifically need it. Once in your directory, you need to create a YAML file for each action you wish to take. The name doesn’t matter however I created “stage.yml” and “production.yml” for simplicity.

In each of these files, you define a trigger, in this case, a branch push. Then you set your jobs with the specified build image and steps. The steps are where you add your commands for building the theme and then deploy your code. Several details will need to be provided by you.

You will need to provide the private key for an SSH key/value pair that has its public key added to your WP Engine profile. This private key should be stored in an encrypted fashion and not saved in this file. To solve for this we use Github Secrets to create variables to store this private information. Create a secret variable and add your private key contents to it.

Next, you will need to specify the paths you are copying from and to between your repo and the destination environment. Finally, you will want to define any files and directories you might want to be ignored in this deployment by specifying them in a “.deployignore” file in the base of your repo. This is formatted the exact same way that a git “.gitignore” file is formatted.

Once you have defined all of that, you should not forget to add any pre-deployment steps before the deployment portion of the action. This is where I defined an npm install and production build.

Here is what my file looks like: https://gist.github.com/pthurmond-vmlyr/dde03210691a703cf145fdbd50e92879

(don’t worry, nothing harmful was shared in that file).

You can find WP Engine’s article on this here: https://wpengine.com/support/github-action-deploy/

Challenges

There are several challenges with this setup. First, SSH public key must be added to your own WP Engine profile instead of directly to the project. This is a problem because if you are ever removed from the project then the deployments will start failing.

The second challenge is that this tool provided by WP Engine bypasses their git repo that it defaults to in favor of using SSH to rsync files from GitHub to the environments. This works but seems to be in bad form. To fix this in the future we would need to build a far more complex deploy script that copies files from one repository to the next. We do this very thing with Acquia but it is a somewhat slow process. In this case, with WP Engine providing us with their action for this, it seems reasonable to conclude that they consider this a standard practice.

Conclusion

This was a good exercise for learning how to build a GitHub action for a specific host. I want to eventually build a library of build and deploy processes that we can standardize around and pull down the parts we need specific to each project.

If you would like to dive deeper into the WP Engine Github Action, look here: https://github.com/wpengine/github-action-wpe-site-deploy