Automatically Deploying Your WordPress Site with Bitbucket Pipelines

It's a great practice to use a version control system to automatically deploy your WordPress site when changes occur. Automatically deploying from version control makes sure that your code is always up to date with the latest changes and avoids the potential issues caused by manually uploading file changes.

In this article, we'll show you how to deploy your WordPress site's files using Bitbucket Pipelines.

Initial Setup

Test In Staging First

When making any changes to your WordPress site, it's important to test those changes on a staging environment before making them on a live site. This is especially true when setting up any sort of deployment mechanism, as a misconfiguration can cause downtime or even data loss.

Setting Up Your Bitbucket Repository

When deploying from version control, you'll want to ensure that your repository matches your live site. When an automatic deployment runs, your site's files will be changed to match what's in version control.

If you have plugins or themes on your site that don't exist in version control, they will be deleted after a deployment runs. Likewise, if there are any files inside your repository that you don't want on your live site, you'll want to remove or exclude them before running your deployment pipeline.

Failure to correctly set up your repository can (and often will) result in data loss!

For more information on how automatic deployments operate and how to set up your git repository, see our article on setting up git repositories for automatic deployments.

Creating a New Integration in Atomic

To simplify the process of communicating with Bitbucket Pipelines and other 3rd-party services, Pagely offers an easy-to-use interface for creating different integrations. These integrations make the process of creating credentials a breeze.

Before continuing to the next section, you'll need to create an integration inside Atomic. To learn more, see our article on creating a new integration in Atomic.

Setting Up Your Integration's Secret in Bitbucket

For security purposes, we recommend setting up your credentials as variables within your Bitbucket settings, rather than defining them in plain text inside your pipeline. Here's how to set up the variables that you'll need for following this guide:

1. Start by logging into Bitbucket and accessing the repository that you want to deploy from.
2. Next, access your repository settings by clicking on Repository Settings within the left side menu.
   
   
3. From within your repository's settings area, look to the left side menu and click on Repository Variables.
   
   
4. To authenticate your pipeline, Pagely uses a secret token that we'll now add as a variable. Let's enter PAGELY_INTEGRATION_SECRET into the Name field of our new variable.
   
   
5. For our variable's value, we're going to use the Integration Secret provided by our integration inside Atomic. Copy it from within Atomic, then paste it into the Value field.
   
   
6. For security, we'll want to make sure that this token does not display within the pipeline's logs. To do that, enable the Secured checkbox.
   
   
7. Finally, click on the Add button to save the new variable.
   
   

Creating a Deployment Pipeline

To make your deployment pipeline as simple as possible, we've released a Docker container to handle all of the heavy lifting. All you'll need to do is add a step to your pipeline and include the variables we've exposed.

Here's an example of what a pipeline that uses our deployment step would look like:

# This is an example pipeline that deploys to Pagely.
image: atlassian/default-image:2
  
pipelines:
  default:
    - step:
        script:
          - pipe: pagely/pagely-vps-deploy:1
            variables:
              PAGELY_DEPLOY_DEST: "/httpdocs"
              PAGELY_INTEGRATION_SECRET: $PAGELY_INTEGRATION_SECRET
              PAGELY_INTEGRATION_ID: "HhYn7RelGEiYFJz7nzvKl9"
              PAGELY_APP_ID: "12345"
              PAGELY_WORKING_DIR: $BITBUCKET_CLONE_DIR

If you're already familiar with using Bitbucket pipelines, just grab the step (or the whole pipeline configuration) from above, drop it into your pipeline's YAML file, and edit the variables as you see fit. If not, here's a few steps to get you going:

1. Start by creating a bitbucket-pipelines.yml file inside your repository's root directory or open the file in your favorite editor if it already exists.
2. Inside the new file, you can copy our entire example from above into your new pipeline.
   
   If you're working with an existing pipeline and want to maintain your existing build steps, you can append the step from the example to your existing steps.
3. Next, you'll want to adjust a few variables. The first of these is the PAGLEY_DEPLOY_DEST. Inside this variable, you can set the destination path that you want to deploy to.
   
   In our example, we're using /httpdocs, which will deploy your repository to the root directory of your site.
   
   If you're deploying a single plugin or theme, you'd modify this to reflect your path. For example, if you're configuring a repository that houses a single theme, you would use something like /httpdocs/wp-content/themes/example-theme-directory.
   
   For more information on this and other variables, see our deployment Docker container reference documentation.
4. The next variable is the PAGELY_INTEGRATION_SECRET. Since our example pipeline is reading from a Bitbucket repository variable, you won't need to change this unless you're using a different variable name.
5. Two other variables you'll need to set are the PAGELY_INTEGRATION_ID and PAGELY_APP_ID. Both of these variables can be found within the integration that you created inside Atomic. Since these are both just identifiers, it's safe to either insert them in plain-text like in our example, or optionally create variables for them inside Bitbucket.
6. Our last variable is optional, but worth mentioning. If your build configuration requires it, you can use PAGELY_WORKING_DIR to change the working directory that you deploy from. In our example, this is set to the pipeline's default working directory.
   
   Unless you're deploying from a different directory, you can leave it as-is.

Once your bitbucket-pipelines.yml file is configured, triple-check it over. If it looks good, push it to Bitbucket. Now that the pipeline configuration is in place, your repository's changes will run the pipeline and deploy your WordPress site to Pagely!

As always, if you have any questions, feel free to reach out to Pagely support for further assistance!