Triggers

Updated 2 weeks 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.

Triggers allow you to execute a Workflow or Pipeline automatically, according to events or other conditions. 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.

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.

Intended Audience

  • DevOps

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.

Field

Description

Name

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

Description

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

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.

Actions: Specify the artifact for the Trigger to watch. The artifacts listed here are pulled from Services in your Application.

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.

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. Create a Trigger that deploys On New Artifact.

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. For example, to execute the trigger every 12 hours, you would enter 0 */12 ? * *.

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

For a UNIX expression calculator and examples, see cron from Wikipedia.

On New Instance(s) in the Service Infrastructure

Select this option to execute the Trigger when the service infrastructure adds a new instance (virtual server). Only the AWS based service infrastructure with SSH deployment types are eligible for the new instance based trigger.

Actions: Select the Service Infrastructure(s) to use and the Workflow(s) to include.

Note: The workflow(s) you select are executed with the same artifact and other parameters as the last successful execution of the workflow in the service Infrastructure you selected.

On Webhook Event

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

In Event Type, select the event type (push, pull) for the Webhook event. There are different options depending on the repo selected in Repository Type.

Action (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 Action menu blank.

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

After you click SUBMIT, the Trigger is added.

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 https://app.harness.io/api/webhooks/xxxxxx \
    -d '{"application":"xxxxxx","artifacts":[{"service":"micro-service","buildNumber":"micro-service_BUILD_NUMBER_PLACE_HOLDER"}]}'
  5. Copy the curl command and run it in a terminal. The output will be something like this (private information has been replaced with xxxxxx):

    {
    "requestId":"-tcjMxQ_RJuDUktfl4AY0A",
    "status":"RUNNING",
    "error":null,
    "uiUrl":"https://app.harness.io/#/account/xxxxxx/app/xxxxxx/pipeline-execution/-xxxxxx/workflow-execution/xxxxxx/details",
    "apiUrl":"https://app.harness.io/gateway/api/external/v1/executions/-xxxxxx/status?accountId=xxxxxx&appId=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.
  6. To run a deployment from a browser, paste the URL from uiUrl into the browser location field and hit ENTER. The browser will open app.harness.io and display the running deployment.
  7. 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 "https://app.harness.io/gateway/api/external/v1/executions/xxxxxx/status?accountId=xxxxxx&appId=xxxxxx"
    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

Git Webhooks allow you to build or set up apps which subscribe to certain events on github.com, bitbucket.org, and gitlab.com. 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.

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

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.

File-based repo Triggers are currently supported only for Helm deployments. For more information about Helm deployments, see Helm Deployments.

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 Repository Type, select the repo type.
  5. In Event Type, select On Push. When you are done, the Condition will look something like this:
  6. Click Next.
  7. In Actions, in Execution Type, select Workflow or Pipeline.
  8. 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.
  9. Enable the Skip deployment if file(s) not changed option. The repo-related options appear.
  10. 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.
  11. In Branch Name, enter the name of the branch containing the file that will initiate this Trigger.
  12. In File Path, enter the file name for the file that, when changed and Pushed, will execute this Trigger. When you are done, the Skip deployment if file(s) not changed section will look something like this:
  13. Click 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.

Triggers and Queued Workflows

When a Workflow is triggered multiple times in succession, deploying on the same Service Infrastructure, the deployment executions are queued. 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 Service Infrastructure by using Workflow variables to identify separate namespaces.

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

Each time the Workflow is deployed, manually or using a Trigger, the ${workflow.variables.namespace} value 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

This section covers error messages you might see when creating, updating, deleting, or executing a Trigger. It includes authorization/permissions steps to resolve the errors.

About Triggers and Authorizations

A Trigger involves multiple settings, including Service, Environment, and Workflow specifications. Harness examines these components as you set up a Trigger. You might be authorized for one component selected in a Trigger, such as a Service, but not another, such as an Environment. In these cases, an error message will alert you to missing authorizations.

To determine if you are authorized to create Triggers for a particular Environment or other components, review:

  • All the permissions of your Harness User Group.
  • The Usage Scope of the Cloud Provider, and of any other Harness connectors you have set up.

For further details, see Managing Users and Groups (RBAC) and Connectors Overview.

User does not have "Deployment: execute" permission

Error messages of the form User does not have "Deployment: execute" permission indicate that your user group's Application Permissions > Action settings do not include execute in the scope of the specified Application and/or Environment. To resolve this, see Application Permissions.

User not authorized

The following error message indicates that a non-Administrator has tried to submit a Trigger whose Workflow Variables: Environment field is configured with a variable, rather than with a static Environment name:

User not authorized: Only members of the Account Administrator user group can create or update  Triggers with parameterized variables

Submitting a Pipeline Trigger that includes such a Workflow will generate the same error.

One resolution is to set the Environment field to a static value. But if the Environment setting must be dynamic, a member of the Account Administrator user group will need to configure and submit the Trigger.


How did we do?