GitHub Action for WP Engine Site Deployments

Last updated on October 12th, 2021

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 TPO 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.

Table of Contents

1. Setup Instructions

2. Example GitHub Action Workflow

2.1. Simple main.yml:

2.2. Extended Sample main.yml

3. Environment Variables and Secrets

3.1. Required

3.2. Optional

4. Further Reading

Setup Instructions

Check out this video for a quick walkthrough, and review the extended steps below.

Copy the main.yml found bekow to .github/workflows/main.yml in the root of your local WordPress project/repo.
Replace values of PRD_BRANCH, PRD_ENV for the branch and WP Engine environment name of your choice
- Optional vars can be specified at this point as well. See Environment Variables for more options.
Generate a new SSH key pair if you have not already done so.
Add the SSH Private Key to your Github repo settings: Repo > Settings > Secrets > Actions Secrets > New Repository Secrets
Save the new secret “Name” as: WPE_SSHG_KEY_PRIVATE. More reading available here for Repo Secrets.
Add SSH Public Key to WP Engine SSH Gateway Key settings. This Guide will show you how.
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

Simple main.yml:

name: Deploy to WP Engine
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest  
    steps: 
    - uses: actions/checkout@v2
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/[email protected]
      with:
      
      # Deploy vars
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }} 
      
      # Branches & Environments 
        PRD_BRANCH: main
        PRD_ENV: prodsitehere

Extended Sample main.yml

name: Deploy to WP Engine
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest  
    steps: 
    - uses: actions/checkout@v2
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/[email protected]
      with:
      
      # Deploy vars 
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }} 
        PHP_LINT: TRUE
        FLAGS: -azvr --inplace --delete --exclude=".*" --exclude-from=.deployignore
        CACHE_CLEAR: TRUE
        TPO_SRC_PATH: "wp-content/themes/genesis-child-theme/"
        TPO_PATH: "wp-content/themes/genesis-child-theme/"
      
      # Branches & Environments 
        PRD_BRANCH: main
        PRD_ENV: prodsitehere
        
        STG_BRANCH: feature/stage
        STG_ENV: stagesitehere
        
        DEV_BRANCH: feature/dev
        DEV_ENV: devsitehere

Environment Variables and Secrets

Required

Name	Type	Usage
`PRD_BRANCH`	string	Insert the name of the Github branch you would like to deploy from, example; main.
`PRD_ENV`	string	Insert the name of the WP Engine environment you want to deploy to.
`WPE_SSHG_KEY_PRIVATE`	secrets	Private SSH Key for the SSH Gateway and deployment. See below for SSH key usage.

Optional

Name	Type	Usage
`STG_BRANCH`	string	Insert the name of a staging Github branch you would like to deploy from. Note: exclude leading / from branch names.
`STG_ENV`	string	Insert the name of the WP Engine Stage environment you want to deploy to.
`DEV_BRANCH`	string	Insert the name of a development Github branch you would like to deploy from. Note: exclude leading / in branch names.
`DEV_ENV`	string	Insert the name of the WP Engine Dev environment you want to deploy to.
`PHP_LINT`	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.
`CACHE_CLEAR`	bool	Optionally clear cache post deploy. This takes a few seconds. Default is TRUE.
`TPO_SRC_PATH`	string	Optional path to specify a theme, plugin, or other directory source to deploy from. Ex. `"wp-content/themes/genesis-child-theme/"` . Defaults to “.” Dir.
`TPO_PATH`	string	Optional path to specify a theme, plugin, or other directory destination to deploy to. Ex. `"wp-content/themes/genesis-child-theme/"` . Defaults to WordPress root directory.