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.

  1. SSH PRIVATE KEY SETUP IN GITHUB

NOTES

  • 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!
  • SHA1 has been deprecated. When generating SSH keys for continuous integration, use ED25519 formatting instead.
  1. SSH PUBLIC KEY SETUP IN WP ENGINE

NOTE

This Action DOES NOT utilize WP Engine GitPush or the GitPush SSH keys found here.

  1. 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 Variables & Secrets” for more available options.

  1. 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@v3
    - 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@v2
    - 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-from=.deployignore
        SCRIPT: "path/yourscript.sh"
        CACHE_CLEAR: TRUE

Environment Variables and Secrets

Required

NameTypeUsage
WPE_SSHG_KEY_PRIVATEsecretsPrivate SSH Key for the SSH Gateway and deployment. See below for SSH key usage.

Deploy Options

NameTypeUsage
WPE_ENVstringInsert the name of the WP Engine environment you want to deploy to. This also has an alias of PRD_ENVSTG_ENV, or DEV_ENV for multistep workflows.
SRC_PATHstringOptional subdirectory or file within a repo to deploy from other than the root directory of the source (GitHub) repo. Ex. "wp-content/themes/genesis-child-theme/". If unspecified, src_path defaults to the root of filesystem.
REMOTE_PATHstringOptional subdirectory or file within a repo to deploy to other than the root directory of the remote (WP Engine) repo. Ex. "wp-content/themes/genesis-child-theme/". If unspecified, src_path defaults to the root of filesystem.
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.
SCRIPTstringRemote 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_CLEARboolOptionally clear cache post deploy. This takes a few seconds. Default is TRUE.

Advanced Versioning and Deployment Scenarios

Scenario 1: Full Site Deploy

Deploy all files from a WordPress repo (i.e. my-wp-site/.git) to the root directory of WordPress within WP Engine. 

In this scenario, SRC_PATH and REMOTE_PATH are left empty for default deployment. 

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

Scenario 2: Theme Repo Deploy

Deploy all files from a theme repo (i.e. my-wp-site/wp-content/themes/my-theme/.git) to the theme directory of WordPress on WP Engine. 

In this scenario, only REMOTE_PATH is required. The SRC_PATH may be left blank since the repository is in the root of the theme directory. 

- 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
        REMOTE_PATH: "wp-content/themes/genesis-child-theme/"

Scenario 3: Subdirectory Deploy

Deploy only a subdirectory of a repository to a WordPress directory on WP Engine. 

For example, deploy the theme directory (i.e my-wp-site/wp-content/themes/my-theme/) of a repo versioning the “wp-content” folder (i.e my-wp-site/wp-content/.git). 

In this scenario, both SRC_PATH and REMOTE_PATH are configured. 

- 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: "themes/my-theme/"
        REMOTE_PATH: "wp-content/themes/my-theme/"

Scenario 4: WordPress Local Atlas Deploy

Deploy a WordPress application directory ( i.e app/public/wp-content/) from an Atlas project in Local that is also versioning a Javascript application (ie. /Local Sites/atlasdemo/.git).

In this scenario, both SRC_PATH and REMOTE_PATH are configured. 

   - 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: "app/public/wp-content/"
        REMOTE_PATH: "wp-content/"

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 hosting for WordPress

See why more customers prefer WP Engine over the competition.