Triggers Reference

Updated 2 weeks ago by Michael Cretzman

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

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

In this topic:

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.

Each time you regenerate a secure token, the preceding token(s) is 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.

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 Type

Event

Action

 Github

 Pull Request

Closed

 

 

Edited

 

 

Labeled

 

 

Opened

 

 

Reopened

 

 

Synchronized

 

 

Unassigned

 

 

UnLabeled

 

Push

n/a

 

Issue Comment

Created

 

 

Deleted

 

 

Edited

GitLab

Push

N/A

 

Merge Request

Sync

Open

Close

Reopen

Merge

Update

 Bitbucket

 On Pull Request

Pull 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 of the Triggers in the account.

You can see the event Id 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

Conditions are ANDed together (boolean AND operation). All Conditions must match an event payload for it to execute the Trigger.

The Trigger must match Source Branch, Target Branch, Header Conditions, Payload Conditions, and JEXL Conditions as an AND operation.

If you want to use OR, NOT or other operators across the payload, simply use JEXL Condition and leave the rest empty.

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 belonging 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 does not 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 is 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 <+trigger.payload.pathInJson> expression, 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.

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.

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 of the 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 is a quick summary of the manual process. This is provided in case the automatic Webhook registration does not 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.

Ensure 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 was able to request Pipeline execution. It does not mean that the Webhook didn't work.

If you see Failed, it is likely that the Pipeline has a configuration issue and the Trigger could not initiate Pipeline 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


Please Provide Feedback