Azure DevOps (ADO) is another popular distributed version control system amongst our customers. ADO is not just a repository management and Version Control System (VCS), but also provides users to create their own workflows with its platform called Azure Pipelines. Users can configure default or custom workflows that can be triggered via various events, such as pull requests being raised, tickets changing status, and also from outside sources.
As more and more teams use ADO 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 ADO Pipelines:
The team has a 3rd party automated testing tool which they run using ADO 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 an ADO Pipeline to orchestrate steps to run some additional scripts/executable post merge or post deployment, such as code quality scans.
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 an ADO (Cloud) Pipeline, and a specific example to make sure we get the right text echo'd to the console log.
Azure requirements
First of all, we need an Personal Access Token (PAT) set up on the ADO side. This gives us a special token to perform certain actions inside ADO, with expiry options and restricted permissions as required.
Note - there may be occasions where "Basic" authentication here with a username and password is required, depending on the target endpoint, but using a PAT gives much greater control over permissions, expiries and scope/purpose of capabilities so should be the preferred option.
Click the cog icon top right in ADO > "Personal access tokens", following this guide to create a relevant token, making sure to select "Build" > "Read & execute" at minimum, if wanting to custom define your permissions.
Make sure to save the Access Token somewhere safe as it won't be visible again unless you regenerate it.
Make sure you have a specific ADO Pipeline in mind you want to trigger. The contents/actions of the workflow don't particularly matter for the purpose of this document, as it's primarily around how to trigger it, and of course this could cover a wide array of scenarios.
The example below shows a custom pipeline called "SFCAPipelinev5" that we want to trigger after a Gearset CI job completes successfully to scan the branch for code quality issues.
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://dev.azure.com/{Organization}/{Project}/_apis/pipelines/{PipelineId}/runs?api-version=7.1Where
<Organization>,<Project>and<PipelineID>need replacing with your relevant details, for example:https://dev.azure.com/SamsOrgName/SamsProject1/_apis/pipelines/3/runs?api-version=7.1
The PipelineID is visible in the URL when editing your pipeline, alongside the Organization and Project names.
The access token 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 organization/project/pipeline names and IDs.
Trigger - Configuration of when this will trigger (on success, failures, or both). Usually we'd expect this to be on "Success" only, but for this example I've ticked both.
Payload - custom
Authentication - Authorization
We need to ensure this is prepended by "Bearer" as shown in the guidance text. So it would become "Bearer XXXXXXXXX" where the X's are replaced with your unique PAT from earlier.
Content-type - application/json
Payload
Depending on the complexity of your ADO Pipeline, this could be a very empty section, but in my example I've included some of the default properties you may want to modify (such as Variables etc, from this page outlining the options) e.g:
{
"previewRun": false,
"yamlOverride": null,
"templateParameters": {},
"resources": {},
"variables": {},
"stagesToSkip": [],
"stagesToRun": []
}
Once saved, we can now test the webhook integration to verify it has triggered the job on ADO. 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 ADO side - showing as "Manually triggered", the job has ran successfully, and a successful HTTP 200 code received from ADO when checking the CI job settings in Gearset.
As you can see, we have now successfully triggered an ADO 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 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.