Bitbucket Pipe for WP Engine Site Deployments

If you need to deploy WordPress® code from a Bitbucket repo to WP Engine, use our WP Engine Bitbucket Pipe.¹ Deploy a full site directory or any sub-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 Bitbucket here.

---

Setup Instructions

Configuration requires three main steps: Save a private SSH Key to Bitbucket, save a public SSH key to WP Engine, and set up bitbucket-pipelines.yml to orchestrate the deploy.

STEP 1: SSH PRIVATE KEY SETUP IN BITBUCKET

1. Generate a new SSH key pair, if you have not already done so.
2. Add the base64 SSH Private Key to your Repository Variables  or your Workspace variables.
   • Note: Bitbucket requires base64 encoding to store keys. This guide will outline how to copy in the proper format
3. Save the new secret “Name” as WPE_SSHG_KEY_PRIVATE

STEP 2: SSH PUBLIC KEY SETUP IN WP ENGINE

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

STEP 3: YML SETUP

1. Create a bitbucket-pipelines.yml file in the root of your repo locally. Copy and paste the configuration from below, replacing the value under branches: and the value for WPE_ENV:
2. To configure deploy for another branch, the bitbucket-pipelines.yml can be extended with an additional workflow. See below example for details. 

This provides the ability to perform a different workflow for different branches/environments. Consult “Bitbucket Branch Workflows”  for available options.

STEP 4: GIT PUSH YOUR SITE TO THE BITBUCKET REPO

The action will do the rest!

View your pipelines progress and logs by navigating to the “Pipelines” tab in your repository.

---

Example Bitbucket Pipeline Workflow

Copy and paste a configuration from below, replacing the value under branches: and the value for WPE_ENV:

Simple bitbucket-pipelines.yml:

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Production
          script:
          - pipe: wpengine/wpe-site-deploy:v1
            variables:
              WPE_SSHG_KEY_PRIVATE: $WPE_SSHG_KEY_PRIVATE
              WPE_ENV: '<sitename>'

Extended Sample bitbucket-pipelines.yml:

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Production
          script:
          - pipe: wpengine/wpe-site-deploy:v1
            variables:
              WPE_SSHG_KEY_PRIVATE: $WPE_SSHG_KEY_PRIVATE
              WPE_ENV: '<sitename>'
    staging:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
          - pipe: wpengine/wpe-site-deploy:v1
            variables:
              WPE_SSHG_KEY_PRIVATE: $WPE_SSHG_KEY_PRIVATE
              WPE_ENV: '<sitename>'

---

Environment Variables and Secrets

Required

Name	Type	Usage
WPE_SSHG_KEY_PRIVATE	secrets	Base64 encoded 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.
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 This pipe defaults to a non-destructive deploy using the flags -azvr --inplace --exclude=".*" Caution: Setting custom rsync flags replaces the default flags provided by this pipe. 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

---

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