Trigger a Deployment using cURL

Updated 2 weeks ago by Michael Cretzman

For GitHub, GitLab, and Bitbucket, you can trigger Build Workflows or a Build and Deploy Pipeline in response to a Git event using Webhooks using a Harness On Webhook Event Trigger.

For Custom Git providers, you can trigger any type of Workflow using a Harness On Webhook Event Trigger.

This is described in Trigger Deployments using Git Events.

Once you have created a Harness On Webhook Event Trigger, Harness creates a Manual Trigger for it.

You can do the following with a Manual Trigger:

This topic describes how to obtain and use the cURL command.

For GitHub, GitLab, and Bitbucket, this option is used to execute a Build Workflow or a Build Pipeline only.

In this topic:

Before You Begin

Limitations

In the Actions section of the Trigger, the Deploy only if files have changed option is available for Workflows deploying Kubernetes or Native Helm Services only.

Step 1: Create the Git Webhook Trigger

Follow the steps in Trigger Deployments using Git Events.

When you are finished, the Trigger is displayed in the Triggers list, and includes a Manual Trigger option.

Step 2: Get and Run the cURL Command

Click Manual Trigger.

In the Manual Trigger, 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"}]}'

Copy the curl command, replace the placeholders with actual values, and run it in a terminal.

Review: 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 https://app.harness.io/api/webhooks/xxxxxx \
-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 https://app.harness.io/api/webhooks/xxxxxx \
-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):

{
"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.

See Trigger a Deployment using a URL.

apiUrl can be used to track deployment status programmatically, such as using a REST call.

See Get Deployment Status using REST.

Placeholders and Workflow Variables

In the cURL command, placeholder values are added for any Workflow variables rather than the variables selected when creating the Trigger.

The placeholder values added to the cURL command override any existing values, including Workflow variables selected in the Trigger.

You can choose to ignore the placeholders and not pass values for any variables in the cURL command.

Option: Enforce API Keys for Manual Triggers

Currently, this feature is behind a Feature Flag. Contact Harness Support to enable the feature. Feature Flags can only be removed for Harness Professional and Essentials editions. Once the feature is released to a general audience, it's available for Trial and Community Editions.

Once you have On Webhook Event Trigger you can use a Manual Trigger to start a deployment using a cURL command provided by Harness.

By default, the cURL command does not require that you include Harness API keys. Harness provides the option to enforce the use of API keys in Manual Trigger cURL commands per Application.

By using Harness API keys in your cURL commands, you can enforce authorization on manual execution of your Triggers. Harness API keys let you select which Harness User Groups can run the Trigger.

Permissions Required

  • Account Permissions: to enforce API keys for manual triggers, your Harness User account must belong to a User Group with the Manage Applications Account Permissions option enabled. See Managing Users and Groups (RBAC).
  • Application Permissions: to initiate any manual triggers (with or without using API keys), the Harness User account must belong to a User Group with the Deployments Permission Type and the Execute Workflow and/or Execute Pipeline Application Permissions.

Enforce API Keys for Manual Triggers

To enforce API keys for manual triggers, do the following:

In Harness, in Security, click Access Management.

Click API Keys, and then follow the steps in API Keys to create an API key. Or you can select an existing key.

Make sure your API key is assigned a User Group that only contains the Harness Users that you want to use this API key to run the Manual Trigger cURL command.

In the new or existing Harness Application containing your Triggers, click more options (︙) and select Edit.

Select Authorize Manual Triggers. Harness presents a warning:

Warning: When you select "Authorize Manual Triggers" it will become mandatory to provide API keys in headers to authorize Manual Triggers invocation.

This means that every Manual Trigger cURL command now includes a placeholder for the API key (x-api-key_placeholder):

curl -X POST -H 'content-type: application/json' 
-H 'x-api-key: x-api-key_placeholder'
--url https://app.harness.io/trigger-authorization/api/webhooks/o5w0h6H8Xmllbdp?accountId=wAwixrZwvnhuGVQOJ3sD
-d '{"application":"T6fPlBO4TWKT-fCPXxamxA"}'

Replace the x-api-key_placeholder with the Harness API key.

That's it. Now you have authorization set up on your Manual Trigger.

Let's look at the two use cases:

  • Authorize Manual Triggers is disabled: the standard Manual Trigger cURL command configuration is used. Manual Trigger cURL commands will not contain the API placeholder or require an API key. If an API key is still provided, Harness checks if the provided key is authorized to invoke the Trigger. Meaning, it checks to see if the User Group assigned to the key has the required Application Permissions (listed above). If User Group assigned to the key does not have the required Application Permissions, then the Trigger cannot be invoked and an error message appears.
  • Authorize Manual Triggers is enabled: if the User Group assigned to the API key has the required Application Permissions (listed above), then the Trigger is invoked.

Configure As Code

To see how to configure the settings in this topic using YAML, configure the settings in the UI first, and then click the YAML editor button (</>).


How did we do?