Skip to main content

Custom Notification templates for Pipeline Notifications

note

Currently this feature is behind Feature Flag: PIPE_CUSTOM_NOTIFICATION_TEMPLATES

You can create custom notification templates to customize notification content and reuse templates across Centralized Pipeline Notifications. These templates support Pipeline Expressions and RBAC controls, giving you both flexibility and security.

With this enhancement, you can attach a custom notification template to a notification rule and override the default message format with a custom webhook payload.

Custom templates let you:

  • Control the structure and content of your notifications.
  • Use dynamic expressions (such as pipeline or stage variables).
  • Reuse templates across multiple pipelines and teams.

In this section, you'll learn how to set up notifications for pipeline events using custom notification templates at a specific scope.

You can create custom notification templates at the following scopes: Account, Organization, and Project.

There are two ways to use custom notification templates:

Setting Up Notifications Template​

note
  • Custom Notification templates support usage of template variables.
  • Custom Notification templates will be an inline entity, meaning they cannot be stored in Git.
  • All Pipeline and Stage-level variables are supported. If an expression cannot be resolved, it will return an empty string.
{
  "pipeline name": "pipeline",
  "stage name": "",
  "stage type": ""
}

In this example, we are going to discuss setting up custom notification template for Pipeline at Project Level:-

Attaching a Custom Notification Template to Pipeline Notifications​

Harness supports adding notification rules to pipelines. With this enhancement, you can now attach a custom notification template to a pipeline notification rule to override the default message format and send custom webhook-based notifications.

You can also attach templates in centralized notification for pipeline events

This allows you to replace the default notification message with a tailored structure defined in your template, including any runtime variables or expressions you've configured.

How to Attach a Template​

When configuring a pipeline-level notification rule, click Notify in the right panel of the Pipeline Studio. Then, follow the steps for Configure pipeline notifications until you reach the Notification Template step.

Under the Notification Template section:

  • Select your custom notification template.

  • If the template includes runtime variables, you'll be prompted to provide values for those inputs.

Each notification method has a different payload format, so you’ll need to create a separate custom notification template for each method.

Here are the notification methods and their sample payload format:

Here is a sample template for Email notification:

template:
  name: email-template
  type: Notification
  projectIdentifier: samples
  orgIdentifier: default
  tags: {}
  spec:
    body:
      content: |
        subject: Harness Pipeline Notification
        body: |
          Hello,

          Here's a summary of your pipeline execution:

          Pipeline Name: <+pipeline.name>
          Status: <+pipeline.status>

          Stage Name: <+stage.name>

          View Execution:
          <+pipeline.executionUrl>


          Regards,
          Harness CI/CD
      type: YAML
    variables: []
  identifier: email-template
  versionLabel: v0

Here's how the notification would look like when the above template is used in the notification rule:

warning

Each notification method has its own payload format. Ensure that your custom template matches the expected format for the notification method you are using. Any mismatch in the payload format will result in the notification sent in the default format.

Once applied, the custom template overrides the default webhook payload sent during pipeline execution.

Variables in the Notification Template​

Notification templates support runtime inputs, which must be provided when configuring a notification rule—whether at the Centralised Notification Service (CNS) level or the pipeline level.

If a runtime variable is declared in the template, you will be prompted to enter values or expressions for it when selecting that template during notification rule configuration.

Use the following expression format to reference these variables in your template body: <+notification.variables.testVar>

You can access the event type that triggered the notification using: <+notification.eventType>

In case of failure, you can use the expression <+notification.errorMessage> to view failure information for the pipeline/stage/step.

Reconciliation of Notification Rules​

If you update a notification template by adding new runtime variables after it has already been attached to a notification rule, you may need to reconcile the rule to ensure those inputs are provided during execution.

Pipeline-level Notifications​

When a template used in a pipeline-level notification rule configured through the Custom Notification tab is updated, a warning message will appear when you attempt to run the pipeline:

  • "Entities referenced in this pipeline have been updated. Please reconcile and save the pipeline to run the latest version."

You can still proceed with the run, but any newly added variables will default to an empty string unless resolved.

To fully reconcile the rule with the latest version of the template, you need to reselect the template and provide values for the new inputs:

  1. Go to the Notify tab in the pipeline.
  2. Edit the notification rule.
  3. Navigate to the Templates tab.
  4. Reselect the same notification template.
  5. A prompt will appear asking you to enter values for the new runtime variables.

This updates the pipeline YAML to reference the latest template version and ensures all required inputs are captured.

Centralised Notifications​

In Centralised Notification rules, no warning appears when you update a template. However, if a template has changes or new input variables, you can view all the impacted references in the Referenced By section of the template.

To fully reconcile the rule with the latest version of the template, you’ll still need to reselect the template and provide values for the new inputs.

Steps:

  1. Go to Notification Management under Project/Org/Account Settings.
  2. Edit the existing notification rule.
  3. In the Notification Templates step, reselect the same template.
  4. A prompt will appear for you to enter values for the newly added runtime variables.

This process ensures that all new inputs are captured and the rule remains valid.

By re-selecting the updated template in either case, you ensure your rule is aligned with the latest version and that all runtime inputs are explicitly provided.

CD Events Schema​

To align with the CD Events standard, Harness has contributed several notification templates to the public CD Events schema repository based on our supported events.

You can explore these templates here:
CD Events Schema on GitHub

The public repository includes a brief explanation of the schema, structure, and supported event types. If you think anything is missing or requires further clarification, feel free to raise a GitHub issue or contact us.