GitLab is another popular distributed version control system amongst our customers. GitLab is not just a repository management and Version Control System (VCS), but also provides users to create their own workflows with its platform called GitLab 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 GitLab 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 GitLab Pipelines:
The team has a 3rd party automated testing tool which they run using GitLab 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 like Leapwork.
The team is using an GitLab 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 GitLab (Cloud) Pipeline, and a specific example to make sure we get the right text echo'd to the console log.
GitLab requirements
There are 2 options in GitLab for authenticating and triggering a pipeline - one is the usual Personal Access Token (PAT) method as used in other platforms, and the other utilises a pipeline specific 'trigger'. Considering the scenario in this document and our want to trigger a specific pipeline, along with GitLab's recommendation on using pipeline trigger tokens, we'll stick with the trigger capability throughout.
Note - this does mean we'll be passing the token in as part of the URL or body, rather than an Authorization header, which is deemed acceptable from a security standpoint due to the very tightly scoped permissions of trigger tokens. If this isn't deemed to be in line with the security posture for your organization, you could investigate using a PAT, but implicitly they have a much wider scope of permissions and could be classified as more dangerous than a trigger token.
To create a Pipeline trigger:
Go to Settings > CI/CD in your GitLab project.
Scroll to the Pipeline Triggers section.
Click Add Trigger:
Description: Enter a relevant description, such as 'GearsetQA'.
Expiration Date: Set a relevant date you want this token to expire.
Save the trigger.
You can then copy the trigger token out for use later.
Make sure you have a specific GitLab 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 we've created that we want to trigger after a Gearset CI job completes successfully to simply echo some statements, along with using some internal GitLab variables and also custom ones I could pass in if required.
Gearset setup
We now need to switch back into Gearset to configure the outgoing webhook. GitLab is very flexible as to which pieces of information can be placed straight into the URL, or passed as part of the body of the request, such as the branch to trigger and security token. We'll stick with the body of the request for this example.
Some key pieces of information we'll need:
URL -
https://gitlab.com/api/v4/projects/<ProjectID>/trigger/pipelineWhere
<ProjectID>needs replacing with your relevant details, for example:https://gitlab.com/api/v4/projects/12344321/trigger/pipeline
The ProjectID is visible from the main page of your project, on the right hand side, as below.
The pipeline trigger token we created and saved earlier.
Note - you may encounter certain situations where the token will need to be used as part of the webhook URL rather than passed into
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 ProjectID as above.
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 failure.
Payload - custom
Authentication - None
Important - Since we're passing in the gitlab pipeline trigger token as part of the body, we don't need any authentication options set here, so leave this as none.
If you decided to use a PAT instead of the pipeline trigger token, you would need to use 'Authorization' and a Bearer token here. Note the 404 error here if you tried to use a PAT in an incorrect way.
Content-type - application/json
Payload
Depending on the complexity of your GitLab Pipeline, this could be a very minimal section, but in my example I've included some of the default properties you may want to modify (such as specific branches, variables etc, from this page outlining the options as part of pipeline triggers) e.g:
{
"token": "glptt-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"ref": "feature/GitlabPipelineTest",
"variables": {
"DEPLOY_ENVIRONMENT": "staging",
"RELEASE_VERSION": "1.2.3"
}
}Note that I also used a dynamic variable ({{JOB_TARGET}}) from Gearset's options here, outlining the target environment. See below for a summary.
Once saved, we can now test the webhook integration to verify it has triggered the job on GitLab. 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 GitLab side - showing the job outputs with dynamic variable, the job has ran successfully, and a successful HTTP 201 code received from GitLab when checking the CI job settings in Gearset.
As you can see, we have now successfully triggered an GitLab 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.