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.
- 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 production
- You are using the develop branch of your repo for staging
- 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 "master" and "staging". 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 from WP Engine | ❗ |
| PROJECT_TYPE | ("theme" or "plugin") This really just determines what folder your repo is in | ❗ |
| 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 "master" --depth 50 https://github.com/linchpin/wpengine-codeship-continuous-deployment.git
chmod 555 ./wpengine-codeship-continuous-deployment/deploy.sh
./wpengine-codeship-continuous-deployment/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 or staging 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
- Peer review
- Complete documentation for usage (setup pipelines, testing etc).