WP Engine GitHub Action for Site Deployment

Use this GitHub Action to deploy code from a GitHub repo to a WP Engine environment of your choosing. If you do not have a WP Engine Account, click here to get started! If you do have an account, check out our guided step-by-step instructions.

This action enables you to:

Deploy a full site directory or subdirectory of your WordPress install
Perform a PHP Lint
Customize rsync flags
Clear cache
Execute a post-deploy script of your choosing

Setup Instructions

SSH PUBLIC KEY SETUP IN WP ENGINE
- Generate a new SSH key pair if you have not already done so. Please note that this SSH Key needs to be passwordless.

Add SSH Public Key to WP Engine SSH Gateway Key settings. This Guide will show you how.

SSH PRIVATE KEY SETUP IN GITHUB

Add the SSH Private Key to your Repository Secrets or your Organization Secrets. Save the new secret "Name" as WPE_SSHG_KEY_PRIVATE.

YML SETUP

Create .github/workflows/main.yml directory and file locally. Copy and paste the configuration from below, replacing the value under branches: and the value for WPE_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 for branches: and WPE_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

Simple main.yml:

name: Deploy to WP Engine
on:
  push:
    branches:
     - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/github-action-wpe-site-deploy@v3
      with:
        WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
        WPE_ENV: <your_install_name_here>

Extended main.yml

name: Deploy to WP Engine
on:
  push:
    branches:
     - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: GitHub Action Deploy to WP Engine
      uses: wpengine/github-action-wpe-site-deploy@v3
      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=wp-content/mu-plugins/local-plugin --exclude-from=.deployignore
        SCRIPT: "path/yourscript.sh"
        CACHE_CLEAR: TRUE

Environment Variables & Secrets

Required

Name	Type	Usage
`WPE_SSHG_KEY_PRIVATE`	secrets	Private SSH Key for the SSH Gateway and deployment. See below for SSH key usage.

Deploy Options

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 multi-step workflows.
`SRC_PATH`	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.
`REMOTE_PATH`	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.
`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 extended example above is excluding paths specified in a `.deployignore` file in the root of the repo. This action defaults to a non-destructive deploy. For flags that contain whitespace, use single quotes around the flag's value: `FLAGS: -azvr --filter=':- .gitignore'` For flags that do not contain whitespace, quotes are unnecessary. Default: `-azvr --inplace --exclude=.*` Caution: Setting custom rsync flags replaces the default flags provided by this action. Consider also adding the `-azvr` flags as needed. `-a` preserves symbolic links, timestamps, user permissions and ownership. `-z` is for compression `-v` is for verbose output `-r` is for recursive directory scanning
`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 page and CDN cache post deploy. This takes a few seconds. Default is TRUE.

Versioning

We follow SemVer and GitHub's action versioning recommendations for maintaining major, minor, and patch version tags. Patch tags (e.g. v1.1.1) are created for each release and will not move once created. Major tags (e.g. v1) and minor tags (e.g. v1.1) will be updated to track their respective latest versions.

We recommend binding this action to the latest major tag so that you will receive backwards compatible updates.

wpengine / github-action-wpe-site-deploy

readme