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


Setup Instructions

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

  1. Copy the main.yml found bekow to .github/workflows/main.yml in the root of your local WordPress project/repo.
  2. Replace values of PRD_BRANCHPRD_ENV for the branch and WP Engine environment name of your choice
  3. Generate a new SSH key pair if you have not already done so.
  4. Add the SSH Private Key to your Github repo settings: Repo > Settings > Secrets > Actions Secrets > New Repository Secrets
  5. Save the new secret “Name” as: WPE_SSHG_KEY_PRIVATE. More reading available here for Repo Secrets.
  6. Add SSH Public Key to WP Engine SSH Gateway Key settings. This Guide will show you how.
  7. 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/[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 }} 
      
      # 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/[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 }} 
        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

NameTypeUsage
PRD_BRANCHstringInsert the name of the Github branch you would like to deploy from, example; main.
PRD_ENVstringInsert the name of the WP Engine environment you want to deploy to.
WPE_SSHG_KEY_PRIVATEsecretsPrivate SSH Key for the SSH Gateway and deployment. See below for SSH key usage.

Optional

NameTypeUsage
STG_BRANCHstringInsert the name of a staging Github branch you would like to deploy from. Note: exclude leading / from branch names.
STG_ENVstringInsert the name of the WP Engine Stage environment you want to deploy to.
DEV_BRANCHstringInsert the name of a development Github branch you would like to deploy from. Note: exclude leading / in branch names.
DEV_ENVstringInsert the name of the WP Engine Dev environment you want to deploy to.
PHP_LINTboolSet to TRUE to execute a php lint on your branch pre-deployment. Default is FALSE.
FLAGSstringSet 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_CLEARboolOptionally clear cache post deploy. This takes a few seconds. Default is TRUE.
TPO_SRC_PATHstringOptional path to specify a theme, plugin, or other directory source to deploy from. Ex. "wp-content/themes/genesis-child-theme/" . Defaults to “.” Dir.
TPO_PATHstringOptional 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.

Further Reading


NEXT STEP: Check out our best practices for deploying when using version control

Still need help? Contact support!

We offer support 24 hours a day, 7 days a week, 365 days a year. Log in to your account to get expert one-on-one help.

The best in WordPress hosting.

See why more customers prefer WP Engine over the competition.