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

NOTES

  • If using a Bitbucket Workspace, adding the SSH key to the Workspace Variables will allow all repos to reference the same SSH key for deploys. The SSH Key also grants access 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.
  • SHA1 has been deprecated. When generating SSH keys for continuous integration, use ED25519 formatting instead.

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.

NOTE

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

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

NameTypeUsage
WPE_SSHG_KEY_PRIVATEsecretsBase64 encoded Private 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.
SRC_PATHstringOptional 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_PATHstringOptional 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_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 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
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 page and CDN cache post deploy. This takes a few seconds. Default is TRUE

NOTE

As this script does not restrict files or directories that can be deployed, it is recommended to leverage one of WP Engine’s .gitignore templates.


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.