There is plenty to appreciate about WP Engine as a WordPress platform and we have been a partner for quite some time. Caching, Multiple sites, backup, multi user, support. All great features. The one that falls flat in our opinion is their Git implementation.
While non-standard would be putting it mildly, the WP Engine Git implementation has so many pitfalls that we have adapted our WP Engine workflow to incorporate Git at WP Engine in a non-cannonical way.
Our non-canonical setup means that the Git repos at WP Engine receives updates but the main repository and source of truth for the site is hosted at Github.
The Pitfalls
Setup
The setup for Git at WP Engine is strange in that there is a repository URL under each environment which would make you think that you could add your ssh key and clone the main/master branch to your local work environment. This would be false as you would quickly learn there is no branch in the repos.
In the WP Engine instructions for Git setup you will learn that you must first do the following:
- Download a backup for the site
- Initialize a git repos in the folder
- Add a .gitignore
- Make an initial commit of files
- Add your WP Engine Git repos URL as a remote
- Push to the WP Engine repository.
The last part about pushing to WP Engine is important in that you must not make any changes to content before you make this initial push. This should be a 1 to 1 match of the files on your site. The reason for this, is that if you make changes or other commits before doing this initial push, your repository and the files on your WP Engine site will get out of sync.
If you happen to delete a few unused plugins before doing this initial push, you will soon realize that you cannot remove the plugin files from your WP Engine file system via Git. They are basically orphaned and must be removed via SFTP or ssh.
Branches
At the bottom of the WP Engine support Git page you will read the following:
WP Engine support for branches is unique in that whichever branch was last pushed is the one that gets copied to the environment on WP Engine. The previous push takes precedence, so switching branches and attempting to have those changes take precedence will not work.
What this means, is that you SHOULD NOT push a branch to your WP Engine Git repository unless you want that branch to become part of the LIVE environment. Unique is putting it mildly.
What this does in essence is remove the ability to use the Git repository at WP Engine to work on feature branches and share work with more than one developer. If you work on a new feature or design for your website and push that branch up to your production Git repos (eg. bobs-new-nav-design-unfinished) this branch will immediately be promoted as the new master/main branch and pushed to live.
Since each site can have as many as 3 environments (Production/Staging/Development) each of these with their own repository the amount of independent branches this might create with no way to clean up or delete can be astounding.
Files
WP Engine has an extensive list of files that are not allowed for various reasons and sometimes your commit will be rejected by WP Engine because the file, although allowed, is too big. Their “Work around” for this is to use SFTP and put that file on the server but not in your repos. A gotcha for this is that sometimes plugins might have video file types for documentation or a specific file (eg. PDF) might be larger than allowed.
Since the WP Engine “Copy Environment” (Live to Staging or Staging to Development) does not discern between uploads and the core/theme files. Use of the copy environment command from the WP Engine admin can cause havoc with what files you believe are in an environment based on your repository branch and what is actually there.
The Solution
Our solution to the unique setup at WP Engine is to use a separate repository at Github as the canonical (origin) where all work is done, all feature branches are kept and, if needed, we keep a pull-request structure where all merges to the production environment are tested and approved.
The initial WP Engine Git setup must still be adhered to, but in addition, you will setup a separate remote at a provider like Github. Once your initial push is made to WP Engine the same push is made to the new remote. The two remotes should now be in sync.
To make things easier for deploying changes we setup deploy workflows for the main branch (to production) and the staging branch (to the staging environment) on WP Engine. Our Github workflow.yml is reusable for other WP Engine sites in that it uses Github secrets to store the site name variable when determining which site/repos to push to.
All work is then done by making a branch from the Github repository. These branches and changes can then be pushed back up to the canonical origin and when changes need to be reviewed can be merged into the staging branch to be auto deployed to the staging environment on WP Engine. Once everything is approved on staging, a pull request can be made to main/master if that is your workflow or changes can be directly merged into main/master and auto deployed to the live environment.
This setup has made our lives so much easier when dealing with WP Engine infrastructure.