Trigger Workflows and Pipelines

Updated 6 days ago by Michael Cretzman

Triggers automate deployments using a variety of conditions, such as Git events, new artifacts, schedules, and the success of other Pipelines.

To trigger Workflows and Pipeline using the Harness GraphQL API, see Trigger Workflows or Pipelines Using GraphQL API.

You can always execute a Workflow or Pipeline manually, and a Trigger does not change any approval requirements in a Workflow or Pipeline.

When you configure a Trigger, you set the condition that executes the Trigger, whether to execute a Workflow or Pipeline, and then the specific actions of the Trigger, such as what artifact source to use.

In this topic:

For information on passing variables from a Trigger to a Workflow, see Passing Variables into Workflows from Triggers. For information on using Triggers as part of Harness GitOps, see Harness GitOps.

Before You Begin

Add a Trigger

To add a trigger, do the following:

  1. Click Setup.
  2. Click the application that contains the workflow or pipeline you want to trigger.
  3. Click Triggers.
  4. Click Add Trigger. The Trigger dialog appears.

The Trigger dialog has the following fields.




Enter a name for the Trigger that conveys something about the Trigger's purpose or execution criteria.


Describe the purpose of the Trigger.

Condition and Actions

Select the condition that will execute the Trigger. The actions available to the Trigger depend on which condition you select.

On New Artifact

This option triggers a deployment when a new artifact is available (a new file appears in the repo). The Trigger is executed based on file names and not metadata changes.

Select the Artifact Source for this trigger. Enter a Build/Tag Filter for the source, or enter a regular expression to match the build information.

The Build/Tag Filter setting relates to the Artifact Source in a Harness Service:

If you enable Regex in Build/Tag Filter, you can use regex expressions such as develop-*, release-*, etc.

Harness supports standard Java regex. For example, if the intent is to match any branch, the regex should be .* instead of simply a wildcard *.

Actions: Specify the Workflow or Pipeline to deploy.

If more than one artifact is collected during the polling interval (one minute), only one deployment will be started and will use the last artifact collected.

Selecting the Manually pull artifact option in a Harness Service does not initiate a Trigger set up with On New Artifact.
Do not trigger on the latest tag of an artifact, such as a Docker image. With latest, Harness only has metadata, such as the tag name, which has not changed, and so Harness does not know if anything has changed. The Trigger will not be executed. Do not use a static tag for Triggers, use an artifact source instead.

On Pipeline Completion

Select a Pipeline that, when completed, will execute this Trigger. For example, you might create a pipeline to test a deployment in one environment and then execute a Trigger to execute a second pipeline to deploy to your stage environment.

Actions: Same as On New Artifact.

On Time Schedule

Select how often to execute the Trigger (every minute, hour, etc). All the cron jobs are executed in Universal Time Coordinated (UTC). You can also apply the time condition to new artifacts only.

Actions: Same as On New Artifact except you cannot obtain the artifact from the artifact source.

Trigger Every: This option appears when you select On Time Schedule. If you select Custom, the time format must be a cron quartz expression.

Harness implicitly adds a prefix for seconds so it does not have to be specified explicitly.

For example, to execute the Trigger every 12 hours, the quartz expression would be 0 0 0/12 ? * * *, but you would enter 0 0/12 ? * * * because Harness adds the 0 prefix.

Harness does not support seconds-level granularity in cron expressions when firing Triggers.

For a quartz expression calculator and examples, see Cron Expression Generator & Explainer.

On Webhook Event

This option is used to execute a Build Workflow or a Build Pipeline only.

A Git event that merges code initiates the Trigger for the Build and Deploy Pipeline. The first stage of the Pipeline is a Build Workflow that builds and collects the artifact from the Artifact Source (which is linked to the Git repo).

In Payload Type, select the repository type (GitHub, Bitbucket, GitLab).

In Event Type, select the event type for the Webhook event. There are different options depending on the repo selected in Payload Type.

See Payload and Event Type Matrix.

Actions (GitHub and Bitbucket only): Select the events for the Trigger, such as Opened (GitHub) or Pull Request Created (Bitbucket).

For more information, see Manual Triggers and GitHub Webhooks and File-based Repo Triggers below.

If you are using a repo other than GitHub, Bitbucket, or Gitlab (such as Jenkins or Bamboo), leave the Payload Type menu blank.

Harness will still generate a Webhook that you can use in your repo.

After you click SUBMIT, the Trigger is added.

Payload and Event Type Matrix

The following table displays the payload and event types supported when you select the On Webhook Event option in a Trigger's Condition setting.

This option is used to execute a Build Workflow or a Build Pipeline only.

For details on each event type and its actions, please consult the provider's documentation.

Payload Type

Event Type


On Pull Request

On Repository

On Issue


On Pull Request

On Push

On Delete

On Release

On Package


On Pull Request

On Push

Custom or no selection.

This option is for repos other than the default Git providers.

For example, Bamboo or Jenkins.

On Pull Request

On Push

Manual Triggers and Git Webhooks

You can manually execute a Trigger using a URL, curl command, REST call, or Git Webhook.

Manual Triggers (API, URL)

You can manually deploy a Harness workflow or pipeline using a manual Trigger. You can run a Trigger manually in the following ways:

  • Using a URL provided by Harness.
  • Using a curl command.
  • Use a REST call to get deployment status.

To use a REST call to get deployment status, you need to generate a Harness API key first. Once you have generated an API key in Harness, deployment status can be tracked by making a REST call to Harness.

For more information, see API Keys.

To manually trigger a deployment, or to obtains a deployment's status via a REST call, do the following:

  1. In your Harness application, click Triggers.
  2. In the bottom of each Trigger listed in Triggers is a link for Manual Trigger.
  3. For the trigger you want to use, click Manual Trigger. The Trigger dialog appears.
  4. Click Show Curl Command. The curl command is displayed. It will look something like the this (private information has been replaced with xxxxxx):

    curl -X POST -H 'content-type: application/json' \
    --url \
    -d '{"application":"xxxxxx","artifacts":[{"service":"micro-service","buildNumber":"micro-service_BUILD_NUMBER_PLACE_HOLDER"}]}'
  5. Copy the curl command, replace the placeholders with actual values, and run it in a terminal.

Placeholders and Manual Settings

When you created a Trigger, if you selected values for parameters that are represented by placeholders in the cURL command, you do not need to add values for the cURL placeholders.

If you add values for the cURL placeholders, you will override manual settings in the Trigger.

This is also true for Triggers that execute templated Workflows and Pipelines. If you create a Trigger that executes a templated Workflow or Pipeline, you can select values for the templated settings in the Trigger, but you can still override them in the cURL command.

Let's look at a placeholder example:

curl -X POST -H 'content-type: application/json' \
--url \
-d '{"application":"xxxxxx","artifacts":[{"service":"micro-service","buildNumber":"micro-service_BUILD_NUMBER_PLACE_HOLDER"}]}'

For service, enter the name of the Harness Service.

For buildNumber, enter the artifact build number from the Artifact History in the Service.

For example:

curl -X POST -H 'content-type: application/json' \
--url \
-d '{"application":"xxxxxx","artifacts":[{"service":"Service-Example","buildNumber":"1.17.8-perl"}]}'

The output will be something like this (private information has been replaced with xxxxxx):


The uiUrl can be used directly in a browser. apiUrl can be used to track deployment status programmatically, such as using a REST call.

  1. To run a deployment from a browser, paste the URL from uiUrl into the browser location field and hit ENTER. The browser will open and display the running deployment.
  2. To get deployment status using a REST call (in this example, curl), use the following curl command, replacing API_URL with the URL from apiUrl, and API_KEY with the API key you generated in Harness:

    curl -X GET -H 'X-Api-Key:API_KEY' --url "API_URL"
    For example (private information has been replaced with xxxxxx):

    curl -X GET -H 'X-Api-Key:a1b2c3' --url ""
    The output from the curl command will contain the status of the deployment. These are the same status messages you can see in the Continuous Deployments dashboard, such as: {"status":"SUCCESS"}, {"status":"FAILED"}, {"status":"ABORTED"}, {"status":"QUEUED"}.

Git Webhooks

This option is used to execute a Build Workflow or a Build Pipeline only.

Git Webhook-based Triggers are not intended for Workflows and Pipelines that deploy artifacts. They are designed for Build Workflows and Pipelines that build artifacts in response to Gt events.

Git Webhooks allow you to build or set up apps which subscribe to certain events on,, and

Each event corresponds to a certain set of actions that can happen to your organization and/or repository.

When one of those events is triggered, Git sends a HTTP POST payload to the Webhook's configured URL. You can use a Harness Trigger GitHub/Bitbucket/Gitlab Webhook URL and execute a Harness deployment in response to a Git event.

A Git event that merges code initiates the Trigger for the Build and Deploy Pipeline. The first stage of the Pipeline is a Build Workflow that builds and collects the artifact from the Artifact Source (which is linked to the Git repo).

For details on the payloads of the different repo Webhooks, see GitHub Event Types & Payloads, Bitbucket Event Payloads, and Gitlab Events.

You specify which Git repo to use when creating the Trigger.

For this example, we'll use a Trigger that was set up using GitHub. To get a GitHub Webhook for a Trigger, do the following:

  1. In your Harness application, click Triggers.
  2. In the bottom of each listed Trigger is a link for GitHub Webhook.
  3. For the Trigger you want to use, click GitHub Webhook. The Trigger dialog appears.
  4. Copy the Webhook and use it in GitHub to trigger the deployment.
When you set up the Webhook in GitHub, modify the Content type to application/json. In Which events would you like to trigger this webhook?, you can select Push events and/or Pull requests.

Just the Push Event

Pushes and Pull Requests

In GitHub and the other Git repos, when configuring the Webhook, you can choose which events you would like to receive payloads for. You can even opt-in to all current and future events.

Harness will examine any incoming payload to ensure that it meets the Action you set. You do not need to use the repo's Webhook event settings to match the Action. Simply use the Harness Webhook URL in the repo Webhook URL field.

File-based Repo Triggers

File-based repo Triggers are currently supported only for Native Helm and Helm-based Kubernetes deployments. For more information, see Kubernetes or Helm?.

In some Webhook Trigger scenarios, you might set a Webhook on your repo to trigger a Workflow or Pipeline when a Push event occurs in the repo. However, you might want to initiate the Trigger only when specific files in the repo are changed.

For example, if you have a Trigger that executes a Helm Deployment workflow, and the workflow uses a values.yaml file from a Git repo, you might want to initiate the Trigger only when that values.yaml file is changed.

To control which files initiate a Trigger based on a Webhook Push Event, do the following:

  1. In your Harness application, click Triggers, and then click Add Trigger.
  2. In Name, enter a name and click Next.
  3. In Condition, click On Webhook Event.
  4. In Payload Type, select the repo type.
  5. In Event Type, select On Push.
  6. In Branch Regex, enter the source branch containing the file that will initiate this Trigger.
    See Branch Regex Push and Pull for more details.
    When you are done, the Condition will look something like this:
  7. Click Next.
  8. In Actions, in Execution Type, select Workflow or Pipeline.
  9. In Execute Workflow/Pipeline, select a Workflow or Pipeline to execute on a repo Push event. The Workflow (by itself or in a Pipeline) must use a Git repo, such as a Helm Deployment Workflow Git Connector.
  10. Enable the Deploy only if files have changed option. The repo-related options appear.
  11. In Git Connector, select which of the SourceRepro Providers set up in Harness to use. These are the connections between Harness and your Git repos. For more information, see Add SourceRepo Providers.
  12. In File Path, enter the file name for the file that, when changed and Pushed, will execute this Trigger.
    For multiple file paths, use commas or line breaks as separators. For example, sample-manifests/values.yaml, index.yaml.
    When you are done, the Skip deployment if file(s) not changed section will look something like this:
  13. Click Next and then Submit. Now you can add the Webhook for that Trigger to the repo you selected and when the file you entered is changed and Pushed, the Trigger will execute.

Branch Regex Push and Pull

For merging changes, use the On Pull Request event type and not On Push. There is no source or destination in push. It has an old state and a new state. See Event Payloads from Atlassian.

The On Pull Request has a source and a destination branch. See Pull Request from Atlassian.

The following is a list of exactly which keys the On Pull Request and On Push events refer to:

  • Github — push branch ref: ${ref.split('refs/heads/')[1]}
  • Github — pull branch ref: ${pull_request.head.ref}
  • GitLab — push branch ref: ${ref.split('refs/heads/')[1]}
  • GitLab — pull branch ref: ${object_attributes.source_branch}
  • BitBucket — push branch ref: ${push.changes[0].'new'.name}
  • BitBucket — push branch ref on-premises: ${changes[0].refId.split('refs/heads/')[1]}
    • You must also select event type as Refs_changed.
  • BitBucket — pull branch ref: ${}
  • BitBucket — pull branch ref on-premises: ${pullRequest.fromRef.displayId}

Triggers and Queued Workflows

When a Workflow is triggered multiple times in succession, deploying on the same Infrastructure Definition, the deployment executions are queued automatically. Queuing prevents deployment collision.

There is one exception: When deploying a Kubernetes Service in a Workflow, you can have parallel executions for same Workflow on the same Infrastructure Definition by using Workflow variables to identify separate namespaces.

For example, you could have a Workflow variable named namespace and enter that in the Infrastructure Definition namespace field as ${workflow.variables.namespace}.

Infrastructure Definition example:

Each time the Workflow is deployed, you manually enter a value for the Workflow namespace variable or use a Trigger to pass in a value, and the ${workflow.variables.namespace} variable is replaced with a different namespace. This can happen simultaneously because a different namespace is used each time. You can even update the variable as part of the Pipeline Stage that executes the Workflow.

For more information, see Passing Variables into Workflows and Pipelines from Triggers.

Troubleshooting Trigger Permissions

How did we do?