GitHub Action for WP Engine Site Deployments
If you need to deploy code from a GitHub repo to WP Engine, this is a great option using GitHub Actions. Deploy a full site directory, a theme, plugin, or other directory with the SRC_PATH and REMOTE_PATH options. Other options include performing a PHP Lint, custom rsync flags, or clearing cache.
This configuration uses WP Engine’s SSH Gateway, instead of WP Engine’s GitPush feature.
View the full guide on GitHub here.
Setup Instructions
Configuration requires three main steps: Connect Github and WP Engine, save the private and public SSH keys, and set up the local yml configuration to orchestrate the deploy.
- SSH PRIVATE KEY SETUP IN GITHUB
- Generate a new SSH key pair, if you have not already done so.
- Add the SSH Private Key to your Repository Secrets or your Organization Secrets.
- Save the new secret “Name” as
WPE_SSHG_KEY_PRIVATE
.
NOTE
If using a GitHub Organization, adding the SSH key to the Organization Secrets will allow all repos to reference the same SSH key for deploys using the method in the sample main.yml
. The SSH Key also connects to all installs made available to its WP Engine User. One key can then effectively be used to deploy all projects to their respective sites on WP Engine. Less work. More deploys!
- SSH PUBLIC KEY SETUP IN WP ENGINE
- Add SSH Public Key to WP Engine SSH Gateway Key settings. This Guide will show you how.
NOTE
This Action DOES NOT utilize WP Engine GitPush or the GitPush SSH keys found here.
- YML SETUP
- Create
.github/workflows/main.yml
directory and file locally. Copy and paste the configuration from below, replacing the value underbranches:
and the value forWPE_ENV:
. - To deploy from another branch, simply create another yml file locally for that branch, such as
.github/workflows/stage.yml
and replace the values forbranches:
andWPE_ENV:
for that workflow.
This provides the ability to perform a different workflow for different branches/environments. Consult “Environment Variable & Secrets” for more available options.
- Git push your site GitHub repo. The action will do the rest!
View your actions progress and logs by navigating to the “Actions” tab in your repo.
Example GitHub Action Workflow
name: Deploy to WP Engine
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- name: GitHub Action Deploy to WP Engine
uses: wpengine/[email protected]
with:
WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
WPE_ENV: <your_install_name_here>
name: Deploy to WP Engine
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- name: GitHub Action Deploy to WP Engine
uses: wpengine/[email protected]
with:
# Deploy vars
WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
WPE_ENV: <your_install_name_here>
# Deploy Options
SRC_PATH: "wp-content/themes/genesis-child-theme/"
REMOTE_PATH: "wp-content/themes/genesis-child-theme/"
PHP_LINT: TRUE
FLAGS: -azvr --inplace --delete --exclude=".*" --exclude-from=.deployignore
SCRIPT: "path/yourscript.sh"
CACHE_CLEAR: TRUE
Environment Variables and Secrets
Name | Type | Usage |
---|---|---|
WPE_SSHG_KEY_PRIVATE | secrets | Private SSH Key for the SSH Gateway and deployment. See below for SSH key usage. |
Name | Type | Usage |
---|---|---|
WPE_ENV | string | Insert the name of the WP Engine environment you want to deploy to. This also has an alias of PRD_ENV , STG_ENV , or DEV_ENV for multistep workflows. |
| string | Optional path to specify a directory within the repo to deploy from. Ex. "wp-content/themes/genesis-child-theme/" . Defaults to root of repo filesystem as source. |
| string | Optional path to specify a directory destination to deploy to. Ex. "wp-content/themes/genesis-child-theme/" . Defaults to WordPress root directory on WP Engine. |
| bool | Set to TRUE to execute a php lint on your branch pre-deployment. Default is FALSE . |
FLAGS | string | Set optional rsync flags such as --delete or --exclude-from . The example is excluding paths specified in a .deployignore file in the root of the repo. This action defaults to a non-destructive deploy using the flags in the example above. |
SCRIPT | string | Remote bash file to execute post-deploy. This can include WP_CLI commands for example. Path is relative to the WP root and file executes on remote. This file can be included in your repo, or be a persistent file that lives on your server. |
CACHE_CLEAR | bool | Optionally clear cache post deploy. This takes a few seconds. Default is TRUE. |
Further Reading
- Defining environment variables in GitHub Actions
- Storing secrets in GitHub repositories
- As this script does not restrict files or directories that can be deployed, it is recommended to leverage one of WP Engine’s .gitignore templates.
NEXT STEP: Check out our best practices for deploying when using version control