Add a Trigger

Updated 3 days ago by Michael Cretzman

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.

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 its purpose of the criteria for the trigger.

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 workflow or pipeline to execute. Specify where to obtain the new artifact for the workflow or pipeline. You can obtain the artifact from the artifact source in the condition you set (the Triggering Artifact Source), the last collected artifact source, or the last successfully deployed artifact from a specific pipeline.

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 0 */12 ? * *.

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

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

Select the repository type and event type (push, pull) for the Webhook event.

Actions: The same as On New Artifact with a few exceptions. For more information, see Manual Triggers and Github Webhooks and File-based Repo Triggers below.

After you click SUBMIT, the trigger is added.

Manual Triggers and Github Webhooks

You can manually execute a trigger using a URL, curl command, REST call, or Github Webhook.

Github Webhooks

Github Webhooks allow you to build or set up apps which subscribe to certain events on GitHub.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, Github sends a HTTP POST payload to the Webhook's configured URL. You can use a Harness trigger Github Webhook URL and execute a Harness deployment in response to a Github event.

To get a Github Webhook for a trigger, do the following:

  1. In your Harness application, click Triggers.
  2. In the bottom of each trigger listed in Triggers is a link for Github Webbhook.
  3. For the trigger you want to use, click Github Webbhook. 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, 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.

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/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/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"}.

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. For more information about Helm deployments, see Docker, Kubernetes, and Helm Deployment.

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.

See Also

API Keys

Tour the Harness Platform


How did we do?