Bitbucket is a service from Atlassian that allows you to continuously integrate and deploy your code from your local machine to a git repository using a service called Pipelines. Unlike DeployBot which allows you to push your code to their platform with git, and then uses SFTP to sync your code to WP Engine, Bitbucket uses purely git connections. By the end of this article you’ll have all the knowledge necessary to take your deployments to the next level with Bitbucket Pipelines.
WP Engine Git Setup
First, ensure that you are able to connect to WP Engine’s git system. You don’t need to make any pushes from your local machine yet, however you should be able to run
ssh [email protected] info and see your remote repositories. Ensure that you have your files setup locally that you’re wanting to push. Most prefer to ignore all of the core WordPress files locally in their .gitignore file. You will need to have initialized your repository per WP Engine’s git instructions.
If you have not setup git for WP Engine yet, then follow the directions outlined in our git guide first.
First if you have not already done so, create an Atlassian account through Bitbucket. For most individual developers as well as small teams, the free account will be sufficient as it allows up to 5 users per month for no cost. However, you are limited in the number of allowed “Build” minutes per month when deploying through your Pipelines. So depending on how often you deploy, and the time it takes to build, you may need to consider a paid plan with Bitbucket
Once you’ve created your Bitbucket account it’s time to create your repository. Click the + sign in the left menu bar and select Repository.
Fill out your repository name (you could use your site name here, for example). It’s best to use a private repository and ensure that git is set as the version control system. Then click the Create Repository button.
Now that you’ve created your repository you will need to add Bitbucket as a remote. This will allow you to deploy code from your local machine to Bitbucket. On the Source page for your new repository you’ll see commands to use locally to navigate to your project folder and run the git remote command listed on the page. Use the commands as directed on your local machine.
In Step 2, you will perform your first push to the origin of your master branch. This will create your initial push and get your files into the BitBucket repository.
Now that the initial commit has taken place, create a new branch for your staging environment.
git branch -b staging
git push origin staging
Now if you run
git branch you will see the two local branches, and if you run
git branch -a you’ll see both the local master and staging branches as well as the origin remote branches.
Setting up the Pipelines
Once the branches are setup it’s time to configure your Pipeline on the Bitbucket website. In the left menu, select Pipelines.
Choose PHP as the Language Template, and erase everything that’s provided by default in the yaml file. Replace it with the following, being sure to replace YOUR_ENVIRONMENT_NAME with your WP Engine production and staging environment names.
pipelines: branches: master: - step: script: - git push [email protected]:production/YOUR_ENVIRONMENT_NAME.git master - echo "Pushed to Production" staging: - step: script: - git push [email protected]:production/YOUR_ENVIRONMENT_NAME.git staging - echo "Pushed to Staging"
Upon saving, the pipeline will try to run but will fail as we have not yet provisioned our SSH keys and put them into the WP Engine User Portal.
Navigate to the Settings page of your repository, then click the SSH Keys option from the menu.
Toward the bottom of the SSH Keys page, in the Host Address box, input git.wpengine.com and click Fetch. Ensure the Host Key Fingerprint matches those listed in WP Engine’s git documentation, and proceed. Once the host is setup, you can either generate an SSH Key provided by Bitbucket or upload your own key pair. Once this is generated or uploaded, go back to the User Portal at my.wpengine.com, navigate to your environment’s Git push page, and add a new developer (we recommend using “bitbucket” or something similar so you can easily identify the role of this key).
Now that you have added Bitbucket as a git user for WP Engine, you’ll need to wait 10-20 minutes before you can begin pushing your codebase while the user is fully established. Not to worry, there are more configuration steps to be performed while you wait.
Fetch The Pipeline YAML File
When you setup the Pipeline in a previous step, this created a bitbucket-pipelines.yml file that needs to be fetched into your local repository. In your terminal, run git pull origin master. Now, when you list out the directory you’ll notice the new file that was pulled down.
Test the Pipeline
Once it’s been about 10-20 minutes since adding your SSH Key, make a small change locally, then commit and push to the staging branch by running
git push origin staging. This pushes up your changes to the staging branch on BitBucket, that triggers the staging section of the pipeline to run, which if you configured the pipeline per this guide, will only perform a git push to your staging environment.
Once the push completes locally, navigate back to the BitBucket repository and go to the Pipelines page again. You’ll see a list of the pipeline runs and their status. Click into the most recent one in order to get a better look at the status. If all went well there will be a success message. Otherwise the specific error that WP Engine’s git server returns will be displayed.
If you check your files on WP Engine you’ll see that your changes have now been deployed. To deploy to production you would merge your staging branch (but not delete it), and then perform your push with
git push origin master.