Skip to main content

Add a pipeline notification strategy

This topic describes how to notify users of different pipeline events using popular notification methods.

You can send pipeline event notifications using email and popular communication and incident management platforms.

Event notifications are set up using Notification Rules in your pipeline. You select the types of events to send, and then select how you want to send notifications. When those events occur, Harness sends event information to those channels and recipients.

This topic describes how to set up Notification Rules in your pipeline.

You can set notifications preferences on user groups also. Go to Manage user groups for more information.

Limitations​

Currently, Harness supports several communication and incident management platforms. If you don't see yours, contact Harness.

note

It's important to note most of the Notification Rule settings, including the Slack Webhook URL, cannot be specified using runtime inputs. This information must be provided before the pipeline execution begins. However, you can use expressions to provide this information. Refer to the Input options available in the respective Notification Rule settings for more information.

Requirements​

To create or enable a notification rule, a user must belong to a user group with a role that has the pipeline Create/Edit permission.

Add a notification rule​

In your pipeline, select Notify.

To create a new notification rule, select Notifications. The Notification Rule settings appear.

Enter a name for the notification rule. You might want to edit the name after you've selected the events that trigger the rule.

Select Next.

Select events​

In Pipeline Events, select the events that will trigger the notification.

You can select events for the pipeline or stages.

If you select the stage events, you can select which stages to use.

Select Continue.

There are different communication and incident management platforms to use for the notification rule. Their settings are described below.

The events are self-explanatory, but there are a few considerations:

  • If you select both Pipeline End and Pipeline Success, you'll get two notifications.
  • Pipeline Pause only applies to a manual pause of the pipeline execution. Pending approval steps don't trigger the pipeline pause event.

Email notifications​

For email notifications, simply type in the email addresses that you want to notify.

Enter multiple addresses as a comma-separated list. For example, john.doe@example.io,qateam@example.io.

Here's an example of an email notification for the pipeline Start event:

Along with the start date and who triggered the pipeline, the email includes a link to the pipeline execution in Harness.

Slack notifications​

For Slack notifications, you simply create a webhook in Slack and paste it into the Slack Webhook URL setting in the notification rule.

Follow the steps in Slack documentation for creating a Slack app, selecting your channel, and creating a webhook: sending messages using incoming webhooks.

When you are done, you'll have a webhook that looks something like this:

Copy the webhook.

You either paste the Webhook into Slack Webhook URL or add it as an encrypted text in Harness and reference it here.

For example, if you have a text secret with the identifier slackwebhookURL, you can reference it like this:​

<+secrets.getValue("slackwebhookURL")>​

You can reference a secret within the Org scope using an expression with org:​

<+secrets.getValue("org.your-secret-Id")>​​

You can reference a secret within the Account scope using an expression with account:​

<+secrets.getValue(“account.your-secret-Id”)>​​​

PagerDuty notifications​

For PagerDuty notifications, enter the key for a PagerDuty account or service or add it as an encrypted text in Harness and reference it in PagerDuty Key. Harness will send notifications using this key.

For example, if you have a text secret with the identifier pagerdutykey, you can reference it like this:​

<+secrets.getValue("pagerdutykey")>​

You can reference a secret within the Org scope using an expression with org:

<+secrets.getvalue("org.your-secret-Id")>

You can reference a secret within the Account scope using an expression with account:

<+secrets.getvalue("account.your-secret-Id")>

You can copy or paste this key from PagerDuty's Configuration > Services > Service Details dialog > Integrations tab, as shown below.

For details, see PagerDuty's documentation on creating integrations.

Microsoft Teams notifications​

To set up notifications in Microsoft Teams, you’ll need a webhook URL linked to the channel where you want to receive notifications.

Step 1: Create a Webhook in Microsoft Teams​

  1. In Microsoft Teams, right-click the channel name where you want to send notifications, and select Workflows from the menu.

  1. In the Workflows section, select the workflow Post to a channel when webhook request is received.

  1. Provide a name for the webhook, then click Next.

  1. Select the Team and Channel where you’d like to receive notifications, then click Add Workflow.

  1. A webhook URL will be generated. Copy this URL for use in Harness.

Step 2: Use the Webhook URL in Harness​

In Harness, in Notification Method settings, enter the webhook URL for your Microsoft Teams channel in Microsoft Teams Webhook URL or add it as an encrypted text and reference it here.

For example, if you have a text secret with the identifier teamswebhookURL, you can reference it like this:​

<+secrets.getValue("teamswebhookURL")>​​

You can reference a secret within the Org scope using an expression with org:

<+secrets.getValue("org.teamswebhookURL")>​

You can reference a secret within the Account scope using an expression with account:​

<+secrets.getValue("account.teamswebhookURL")>​​

Webhook Notifications​

Use Webhook notifications to inform an external application of an event.

Select the Webhook notification method, and then enter the URL to be called when the event occurs.

You can also use expressions to compose this URL. For example, https://companyurl.notify.com/execution=-<+pipeline.executionId>.

Note that the expression must be evaluated in the context of the event. For example, stage related expressions may not be valid for pipeline start events.

Add Custom Headers​

Webhook notification method allows you to add custom headers consisting of key-value pairs.

Some important points to note:-

  1. You can add a header by clicking on + Add Header.
  2. You can delete a header by clicking on delete icon.
  3. A header can either be a Fixed value or an Expression.
  4. You can test your webhook integeration by clicking on Test.

Sample pipeline YAML with a webhook notification method, consisting of custom headers:-

notificationRules:
    - name: test
      identifier: test
      pipelineEvents:
        - type: AllEvents
        - type: PipelineStart
        - type: PipelineEnd
        - type: PipelineSuccess
        - type: PipelineFailed
        - type: StageFailed
        - type: StageSuccess
        - type: StageStart
        - type: StepFailed
      notificationMethod:
        type: Webhook
        spec:
          webhookUrl: https://app.harness.io/gateway/ng/api/projects/Quality_Assurence?accountIdentifier=ACCOUNT_ID&orgIdentifier=QE_Team
          headers:
            accept: "*/*"
            authorization: <+pipeline.variables.sv1>
            content-type: application/json
            Status: <+pipeline.status>
            Version: v1
            Content-Encoding: gzip
            Client-ID: <+pipeline.executionId>
            If-Match: xyz
      enabled: true
note
  1. Please note that you should be able to include custom headers while creating custom webhook notifications channel(s) as well as while updating the existing ones.
  2. For a Stage Start event (such as during a deployment stage), the notification summary will include unresolved expressions for services, infrastructure, and environments. This is intentional, as the notification is sent before all references are fully resolved, preventing any potential errors in resolution from causing the stage execution to fail.

For example, a Slack notification when the pipeline completes as well as when it is successful looks something like this:

The webhook call is made as a POST request, and includes a JSON object containing the properties of the triggered event.

If you are using a custom webhook trigger in webhook notification method and if your Pipeline setting Mandate Authorization for Custom Webhook Triggers is true then you need to pass the API key in the header.

JSON for webhook notifications​

{
  "eventData": {
    "accountIdentifier": "ACCOUNT_ID",
    "orgIdentifier": "default",
    "projectIdentifier": "PROJECT_ID",
    "pipelineIdentifier": "PIPELINE_ID",
    "pipelineName": "PIPELINE_NAME",
    "planExecutionId": "PIPELINE_EXECUTION_ID",
    "executionUrl": "https://app.harness.io/ng/#/account/ACCOUNT_ID/cd/orgs/default/projects/PROJECT_NAME/pipelines/PIPELINE_NAME/executions/PIPELINE_EXECUTION_ID/pipeline",
    "pipelineUrl": "https://app.harness.io/ng/#/account/ACCOUNT_ID/cd/orgs/default/projects/PROJECT_NAME/pipelines/PIPELINE_NAME/pipeline-studio",
    "eventType": "PipelineStart",
    "nodeStatus": "started",
    "triggeredBy": {
      "triggerType": "MANUAL",
      "name": "NAME",
      "email": "EMAIL_ID"
    },
    "moduleInfo": {},
    "startTime": "Tue Aug 20 08:14:46 GMT 2024",
    "startTs": 1724141686
  }
}

Notify Slack channels in user groups​

If you have Harness user groups that have Slack webhooks set up in their Notification Preferences, you can select those groups and Harness will notify them in addition to the Email, Slack, or PagerDuty settings.

Go to send notifications using Slack for more information.

Enable or disable notification rules​

Once you've created notification rules, you can enable and disable them in the Notifications page.