Love WordPress? Love WP Engine and want to take advantage of their git deployment but need to have more flexiblity to deploy multiple repos? This script will assist you in automatically deploying WordPress plugins and themes to WP Engine .git deployment using Codeship or other deployment services.
At Linchpin we use WP Engine and Codeship and love both. Hopefully you find this shell script useful.
For a more indepth walk through please visit this article on the Linchpin site.
The latest version of this script will not only deploy your code, the latest version will also build your code as long as the script finds a gulpfile, gruntfile, yarn etc. In order to bild your project simply create a task in your task runner named build:production.
Supports both WP Engine legacy and Multi environment sites (Legacy Staging or Dev, Staging, Production)
- You are using Codeship as your CI/CD solution so you may need to make adjustments based on deploybot or another service.
- You understand how to setup .git deployments on WP Engine already.
- You are using the master branch of your repo for your Production instance
- You are using the staging branch of your repo for your Staging instance
- You are using the develop branch of your repo for your Development instance
- Preflight Repo Setup
- Configuration
- Codeship Environment Variables
- Deployment instructions
- Useful notes
- What this repo needs
When creating your repo, it's important to name the repo using proper folder structure. We typically replace any spaces " " with dashes "-".Example: If your plugin is named "My Awesome Plugin" you can name the repo "my-awesome-plugin". When the script runs it will use the REPO_NAME environment variable as the folder for your plugin or theme. So you may find it useful to match.
Important Note: All assets/files within your repo should be within the root folder. DO NOT include wp-content, wp-content\plugins etc. The deploy script will create all the appropriate folders as needed.
- Log into codeship.com or your deployment method of choice.
- Connect your bitbucket, github or gitlab repo to codeship. (You will need to authorize access to your repo)
- Setup Environment Variables
- Environment variables are a great way to add flexibility to the script with out having variables hard coded within this script.
- You should never have any credentials stored within this or any other repo.
- Create deployment pipeline for each branch you are going to add automated deployments to (For single install setups use "master" and "develop". For multi-environment setups use master, staging, and "develop"). The pipelines you create are going to utilize the deployment script below
- Do a test push to the repo. The first time you do this within Codeship it may be beneficial to watch all the steps that are displayed within their helpful console.
All of the environment variables below are required
| Variable | Description | Required |
|---|---|---|
| REPO_NAME | The repo name should match the theme / plugin folder name | ❗ |
| WPE_INSTALL | The subdomain of your WP Engine install (This is for single installs only and is considered deprecated) | ❗ |
| PROJECT_TYPE | ("theme" or "plugin") This really just determines what base folder your repo should be deployed to | ❗ |
The variables below are not required, but are utilized to work with WP Engine's current multi-environment setup. Moving away from legacy staging, WP Engine now utilizes 3 individual installs under one "site". The are all essentially part of your same hosting environment, but are treated as Production, Staging, and Development environments when it comes to your workflow.
| Variable | Description | Required |
|---|---|---|
| WPE_INSTALL_PROD | The subdomain from WP Engine install "Production" | |
| WPE_INSTALL_STAGE | The subdomain from WP Engine install "Staging" | |
| WPE_INSTALL_DEV | The subdomain from WP Engine install "Development" |
This variable is optional to source a custom excludes list file.
| Variable | Description | Required |
|---|---|---|
| EXCLUDE_LIST | Custom list of files/directories that will be used to exclude files from deploymnet. This shell script provides a default. This Environment variable is only needed if you are customizing for your own usage. This variable should be a FULL URL to a file. See exclude-list.txt for an example | Optional |
You can customize the actions taken by the deployment script by utilizing the following hashtags within your commit message
| Commit #hashtag | Description |
|---|---|
| #force | Some times you need to disregard what WP Engine has within their remote repo(s) and start fresh. Read more about it on WP Engine. |
The below build script(s) will check out the linchpin build scripts from github and then run the shell script accordingly based on the environment variables.
In the script below you will see this script is specifcally for master if you wanted to use this for staging you would setup a deployment that targets develop specifically.
In order to deploy to your pipeline you can use the following command regardless of master, develop or a custom branch. We are utilizing https instead of SSH so we can git clone the deployment script without requiring authentication.
# load our build script from the linchpin repo
git clone --branch "improvement/build-process" --depth 50 https://github.com/linchpin/wpengine-codeship-continuous-deployment.git
chmod 555 ./wpengine-codeship-continuous-deployment/build.sh
chmod 555 ./wpengine-codeship-continuous-deployment/deploy.sh
chmod 555 ./wpengine-codeship-continuous-deployment/build-deploy.sh
./wpengine-codeship-continuous-deployment/build-deploy.sh
-
WP Engine's .git push can almost be considered a "middle man" between your repo and what is actually displayed to your visitors within the root web directory of your website. After the files are .git pushed to your production, staging, or develop remote branches they are then synced to the appropriate environment's webroot. It's important to know this because there are scenarios where you may need to use the #force hashtag within your commit message in order to override what WP Engine is storing within it's repo and what is shown when logged into SFTP. You can read more about it on WP Engine
-
If an SFTP user in WP Engine has uploaded any files to staging or production those assets WILL NOT be added to the repo.
-
Additionally there are times where files need to deleted that are not associated with the repo. In these scenarios we suggest deleting the files using SFTP and then utilizing the #force hash tag within the next deployment you make.
- Tests and Validation
- Complete documentation for usage (setup pipelines, testing etc).