Skip to main content

Webhook Triggers Reference

This topic provides settings information for Triggers. Triggers are used to initiate the execution of Pipelines.

For steps on setting up different types of Triggers, see Triggers Howtos.

Name

The unique name for the Trigger.

ID

See Entity Identifier Reference.

Description

Text string.

Tags

See Tags Reference.

Payload Type

Git providers, such as GitHub, Bitbucket, and GitLab.

Custom Payload type

To use a custom payload type, copy the secure token and add it to your custom Git provider.

Whenever you regenerate a secure token, any preceding tokens become invalid. Update your Git provider with the new token.

Connector

Select the Code Repo Connector that connects to your Git provider account.

See Code Repo Connectors Tech Ref.

note

Git webhook triggers do not support generic Git connectors. You must create provider-specific connectors for each provider (Github, GitLab, Bitbucket, etc) to use them with webhook triggers. For information on each Git provider connector, go to Connect to a Git Repo.

Repository Name

Enter the name of the repo in the account.

Event and Actions

Select the Git events and actions that will initiate the Trigger.

Payload TypeEventAction
 Github Pull RequestClosed
  Edited
  Labeled
  Opened
  Reopened
  Synchronized
  Unassigned
  UnLabeled
 Pushn/a
 ReleaseCreate
  Edit
  Delete
  Prereleae
  Publish
  Release
  Unpublish
 Issue Comment. Only comments on a pull request are supported.Created
  Deleted
  Edited
GitLabPushN/A
 Merge RequestSync
Open
Close
Reopen
Merge
Update
Bitbucket On Pull RequestPull Request Created
  Pull Request Merged
  Pull Request Declined
 Push

Harness uses your Harness account Id to map incoming events. Harness takes the incoming event and compares it to ALL triggers in the account.

You can see the event Id that Harness mapped to a Trigger in the Webhook's event response body data:

{"status":"SUCCESS","data":"60da52882dc492490c30649e","metaData":null,...

Harness maps the success status, execution Id, and other information to this event Id.

Conditions

Optional conditions to specify in addition to events and actions. These help to form the overall set of criteria to trigger a Pipeline based on changes in a given source.

For example:

  • Trigger when a specific value is passed in the source payload.
  • Trigger when there's a change in a specific file or a pull request.
  • Trigger based on a specific artifact tag convention.

Conditions are ANDs

You can think of each Trigger as a complex filter in which all Conditions are AND-ed together. To execute a Trigger, the event payload must match all Conditions in the Trigger.

In this example, an event must match all conditions under Source Branch, Target Branch, Header Conditions, Payload Conditions, and JEXL Conditions for the Trigger to be filtered.

To use OR, NOT, or other operators across the payload, use a JEXL Condition and leave the rest empty.

The JEXL in operator is not supported in JEXL Condition.

Source and Target Branch

The source and target branches of the Git merge that must be matched.

These are available depending on the type of event selected. Any event that belongs to a merge will have Source Branch and Target Branch conditions.

For example:

  • Source Branch starts with new-
  • Target Branch equals main

Built-in Git Trigger and Payload Expressions

Harness includes built-in expressions for referencing trigger details such as a PR number.

Main Expressions
  • <+trigger.type>
    • Webhook.
  • <+trigger.sourceRepo>
    • Github, Gitlab, Bitbucket, Custom
  • <+trigger.event>
    • PR, PUSH, etc.
PR and Issue Comment Expressions
  • <+trigger.targetBranch>
  • <+trigger.sourceBranch>
  • <+trigger.prNumber>
  • <+trigger.prTitle>
  • <+trigger.gitUser>
  • <+trigger.repoUrl>
  • <+trigger.commitSha>
  • <+trigger.baseCommitSha>
  • <+trigger.event>
    • PR, PUSH, etc.
Push Expressions
  • <+trigger.targetBranch>
  • <+trigger.gitUser>
  • <+trigger.repoUrl>
  • <+trigger.commitSha>
  • <+trigger.event>
    • PR, PUSH, etc.

Header Conditions

Valid JSON cannot contain a dash (–), but headers are not JSON strings and often contain dashes. For example, X-Github-Event, content-type:

Request URL: https://app.harness.io:  
Request method: POST
Accept: */*
content-type: application/json
User-Agent: GitHub-Hookshot/0601016
X-GitHub-Delivery: be493900-000-11eb-000-000
X-GitHub-Event: create
X-GitHub-Hook-ID: 281868907
X-GitHub-Hook-Installation-Target-ID: 250384642
X-GitHub-Hook-Installation-Target-Type: repository

The header expression format is <+trigger.header['key-name']>. For example. <+trigger.header['X-GitHub-Event']>.

If the header key doesn't contain a dash (), then the format <+trigger.header['key name']> will work also.

When Harness evaluates the header key you enter, the comparison is case insensitive.

In Matches Value, you can enter multiple values separated by commas and use wildcards.

Payload Conditions

Conditions based on the values of the JSON payload. Harness treats the JSON payload as a data model and parses the payload and listens for events on a JSON payload key.

To reference payload values, you use <+eventPayload. followed by the path to the key name.

For example, a payload will have a repository owner:

...  
> "repository" : {
> "id": 1296269,
> "full_name": "octocat/Hello-World",
> "owner": {
> "login": "octocat",
> "id": 1,
> ...
> },
...

To reference the repository owner, you would use <+eventPayload.repository.owner>. Here's an example using name:

Next, you enter an operator and the value to match. For example:

Referencing Payload Fields

You can reference any payload fields using the expression <+trigger.payload.pathInJson>, where pathInJson is the path to the field in the JSON payload.

For example: <+trigger.payload.pull_request.user.login>

How you reference the path depends on a few things:

  • There are different payloads for different events.
  • Different Git providers send JSON payloads formatted differently, even for the same event. For example, a GitHub push payload might be formatted differently than a Bitbucket push payload. Always make sure the path you use works with the provider's payload format.

JEXL Expressions

You can refer to payload data and headers using JEXL expressions. That includes all constants, methods, and operators in JexlOperator.

Be careful when you combine Harness variables and JEXL expressions.

  • Invalid expression: <+pipeline.variables.MAGIC.toLowerCase()>
    This expression is ambiguous. It could be evaluated as a Harness variable (return the value of variable pipeline.variables.MAGIC.toLowerCase()) or as a JEXL operation (return the lowercase of literal string pipeline.variables.MAGIC).
  • Valid expression: <+<+pipeline.variables.MAGIC>.toLowerCase()> First it gets the value of variable pipeline.variables.MAGIC. Then it returns the value converted to all lowercase.

Here are some examples:

  • <+trigger.payload.pull_request.diff_url>.contains("triggerNgDemo")
  • <+trigger.payload.pull_request.diff_url>.contains("triggerNgDemo") || <+trigger.payload.repository.owner.name> == "wings-software"
  • <+trigger.payload.pull_request.diff_url>.contains("triggerNgDemo") && (<+trigger.payload.repository.owner.name> == "wings-software" || <+trigger.payload.repository.owner.name> == "harness")

Operators

Some operators work on single values and some work on multiple values:

Single values: equals, not equals, starts with, ends with, regex.

Multiple values: in, not in.

The IN and NOT IN operators can take comma-separated values. You can also use regex as a value. For example, Not In master,release/.*.

Pipeline Input

Runtime Inputs for the Trigger to use, such as Harness Service and artifact.

You can use the Built-in Git Payload Expressions and JEXL expressions in this setting.

See Run Pipelines using Input Sets and Overlays.

Webhook

For all Git providers supported by Harness, the Webhook is created in the repo automatically. You don't need to copy it and add it to your repo webhooks.

Git Events Automatically Registered with Webhooks

The following Git events are automatically added to the webhooks Harness registers.

GitHub

GitHub events:

  • create
  • push
  • delete
  • deployment
  • pull_request
  • pull_request_review
GitLab

GitLab events:

  • Comment events
  • Issue events
  • Merge request events
  • Push events
Bitbucket Cloud

Bitbucket Cloud events:

  • issue
  • pull request
Bitbucket Server

Bitbucket Server events:

  • Pull requests
  • Branch push tag

Manually Applying the Webhook

Although Webhooks are applied automatically by Harness, here's a quick summary of the manual process. This is provided in case the automatic Webhook registration doesn't work.

You obtain the Webhook to use in your repo by clicking the Webhook icon.

Log into your repo in the Git provider and navigate to its Webhook settings. For example, here's the Webhooks section of GitHub.

Add a Webhook.

In the Webhook settings, paste the Webhook URL you copied from Harness into the payload URL setting in the repo.

Make sure that you select JSON for the content type. For example, in GitHub, you select application/json in Content type.

Custom Webhook

You enter the webhook in your custom Git provider.

Make sure that the payload content type is JSON (application/json).The format for the custom Webhook is:

https://app.harness.io/pipeline/api/webhook/custom?accountIdentifier=123456789&orgIdentifier=default&projectIdentifier=myProject&pipelineIdentifier=newpipelinetest&triggerIdentifier=myTrigger

The pipelineIdentifier and triggerIdentifier target the Webhook at the specific Pipeline and Trigger.

Is some cases, you will not want to target the Webhook at the specific Pipeline and Trigger. For example, there are events in GitHub that are not covered by Harness and you might want to set up a Trigger for those events that applies to all Pipelines and their Triggers in the Project.

To instruct Harness to evaluate the custom Trigger against all Pipelines (until it finds a Conditions match), remove pipelineIdentifier and triggerIdentifier from the URL before adding it to your repo.

The orgIdentifier and projectIdentifier are mandatory.

Last Execution Details

In a Trigger's details, you can see when the Trigger was executed:

Activation means the Trigger could request Pipeline execution. It doesn't mean that the Webhook didn't work.

If you see Failed, the Pipeline probably has a configuration issue that prevented the Trigger from initiating a Execution.

YAML Example

You can edit your Trigger in YAML also. Click the Trigger, and then click YAML.

trigger:  
name: GitlabNewTrigger
identifier: GitlabNewTrigger
enabled: true
description: ""
tags: {}
orgIdentifier: default
projectIdentifier: NewProject
pipelineIdentifier: testpp
source:
type: Webhook
spec:
type: Gitlab
spec:
type: MergeRequest
spec:
connectorRef: gitlab
autoAbortPreviousExecutions: true
payloadConditions:
- key: <+trigger.payload.user.username>
operator: In
value: john, doe.john
headerConditions:
- key: <+trigger.header['X-Gitlab-Event']>
operator: Equals
value: Merge Request Hook
jexlCondition: (<+trigger.payload.user.username> == "doe" || <+trigger.payload.user.username> == "doe.john") && <+trigger.header['X-Gitlab-Event']> == "Merge Request Hook"
actions: []
inputYaml: |
pipeline:
identifier: testpp
properties:
ci:
codebase:
build:
type: branch
spec:
branch: <+trigger.branch>
variables:
- name: testVar
type: String
value: alpine

Notes