Bitbucket is another popular distributed version control system amongst our customers. Bitbucket is not just a repository management and version control system, but also provides users to create their own workflows with its platform called Bitbucket Pipelines. Users can configure default or custom workflows that can be triggered via various events.
As more and more teams use Bitbucket Pipelines in some form or the other to orchestrate relevant automation steps, it becomes important for a Salesforce DevOps solution like Gearset to integrate with it seamlessly, so that the existing workflows of teams can be utilised the way they are and, if not available directly, can be triggered via Gearset.
Following are few scenarios of teams where they could be using Bitbucket Pipelines -
The team has a 3rd party automated testing tool which they run using Bitbucket Pipeline post package deployment to an org, and want Gearset to trigger such a workflow which in-turn then executes tests. An example may be running a custom selenium test suite, or integrating with a UI testing provider.
The team is using Bitbucket Pipeline to orchestrate steps to run some additional scripts/executable post merge or post deployment
Having a requirement for Gearset to trigger an executable available on a Windows or Linux machine in the cloud or locally.
This guide looks to highlight some key integration requirements and capabilities when using Outgoing Webhooks in Gearset to trigger a Bitbucket (Cloud) Pipeline, and a specific example to make sure we get the right text echo'd to the console log.
Bitbucket requirements:
First of all, we need an App Password set up on the Bitbucket side. This gives us a special token to perform certain actions inside Bitbucket, with expiry options and restricted permissions.
Click the cog icon top right in Bitbucket > Personal Settings > App passwords > Create app password, making sure to select:
Repositories - Write and Admin (Admin is required here to trigger custom pipelines, otherwise the API won't recognise you have access to anything other than default workflows)
Pipelines - Write
Make sure to save the App Password somewhere safe as it won't be visible again.
Configure your 'bitbucket-pipelines.yml' file in root of repo, with default and custom pipelines you want to trigger. The rest of this document will reference how to trigger a custom pipeline. Note how all of your individual pipeline jobs live in this one file and need to be separated between default and custom sections.
The example below shows a custom pipeline called 'UITester' that we want to trigger after a Gearset CI job completes successfully.
Gearset setup:
We now need to switch back into Gearset to configure the Outgoing Webhook. Some key pieces of information we'll need:
URL - https://api.bitbucket.org/2.0/repositories/<Username>/<RepoName>/pipelines/
Where <Username> and <RepoName> need replacing with your relevant details (you can grab these from the URL box when viewing your repository in Bitbucket). E.g https://api.bitbucket.org/2.0/repositories/GearsetIntegrationUser/GearsetPipeline1/pipelines/
The app password we created and saved earlier.
Follow the instructions here to edit an existing CI Job and add a new Outgoing Webhook in.
See the following screenshot for a summary of what we need to complete, with key information as follows:
Description - A useful description (as you may have multiple webhooks and want easy identification)
Outgoing webhook URL - The outgoing webhook URL as above including switched out username/repository name
Trigger - Configuration of when this will trigger (on success, failures, or both). Usually we'd expect this to be on 'Success' only.
Payload - custom
Authentication - Basic
Our username from the URL will be used here, and the password is the App Token from earlier.
Content-type - application/json
Payload
This is the critical section that must match exactly with the custom pipeline you've configured on the Bitbucket side, which is my case was UITester in the 'pattern' tag, e.g:
{
"target": {
"type": "pipeline_ref_target",
"ref_type": "branch",
"ref_name": "master",
"selector": {
"type": "custom",
"pattern": "UITester"
}
}
}ref_name could be necessary if your code references a particular branch to run against, or left as the default base branch, but this depends on the context of your script.
Once saved, we can now test the webhook integration to verify it has triggered the job on Bitbucket. In my example above I used a validation-only job to test it.
Testing:
Below we can see the Pipeline has been triggered on the bitbucket side, the right outputs were received (showing we ran the 'Custom' pipeline and not the 'default' one), and a successful HTTP 201 code received from Bitbucket when checking the CI job settings.
As you can see we have now successfully triggered a Bitbucket Pipeline from a Gearset CI job, allowing whatever script/integration you have in there to kick off after a successful deployment to your org.
In case if you have further questions on how to configure outgoing webhook in Gearset for your own usecase, please reach out to our Support team via the in-app chat.