Skip to content

Notifications

Yontrack has the possibility to send notifications to different backends like webhooks, email, Slack messages, etc.

A notification is the association between an event occurring on an entity and sent to a given channel using some configuration.

For example, a notification can be:

  • event: a build has been promoted
  • entity: the build, the promotion level
  • channel: email
  • channel configuration: the subject & the email addresses
  • an optional custom template

In this example, the body of the email would be a text like "Build B of branch R in project P has been promoted to BRONZE", which various links to Yontrack.

Note

By default, the notifications use the default templates of the events but a custom template can be provided.

Administrators of Yontrack can create and configure the different backends.

Subscriptions can be either local (subscribing to the events on a given branch) or global (subscribing to the events in all Yontrack, regardless of the entity).

Notification backends

See the appendixes for a complete list of the existing notification backends and their configurations.

Subscriptions

Subscriptions can be done at entity level (project, branch, promotion, etc.) or globally.

Local subscriptions

On an entity page (like the page for a project, a branch, etc.), go to the Tools menu and select Subscriptions:

Subscription menu

On the following screen, you can manage the list of subscriptions at this entity level.

List of subscriptions

To create a subscription, select the New subscription command and enter the fields for the subscription:

New subscription

  • events - list of events to listen to
  • keywords - space-separated list of words which will be used to restrict the events being listened to
  • channel - destination for the notification. Depending on the channel being selected, additional fields are needed (for example, for a Slack notification, the Slack channel is required)
  • custom template - if provided, it'll override the default template associated with the event. See the templating section for its syntax.

In the subscription list, you can delete existing subscriptions.

Global subscriptions

The management of the global subscriptions is exactly the same as for the local ones, but for the fact that the global subscriptions are accessible through the Global subscriptions menu.

Note

Global subscriptions can be configured using CasC. For example:

ontrack:
  extensions:
    notifications:
        global-subscriptions:
          - name: On Gold
            events:
              - new_promotion_run
            keywords: "GOLD main"
            channel: slack
            channel-config:
              channel: "#my-channel"
            contentTemplate: |
              Promoted to ${promotionLevel}.

Recordings

For audit and troubleshooting purposes, all notifications are recorded and administrators can have access to them using the Notification records user menu:

Notification records

Each recording has the following columns:

  • timestamp (UTC) - when was the notification actually sent
  • channel - which channel was used by the notification
  • link - link or button to access more information about the notification outcome
  • source - source of the notification (like a subscription)
  • result - outcome of the notification
  • event - event that triggered the notification
  • entity - entity linked to the notification

By clicking on the icon on the left, you can see more details about the notification:

Notification record details

Finally, the administrator can filter recordings on their results or channels.

Examples

This section shows a number of custom templates for some events

Changelog on promotion

To send a changelog on a promotion, subscribe to the new_promotion_run event:

Change log:

${promotionRun.changelog}

If the project builds have linked to a dependency project's builds, it may be interesting to follow the links recursively:

Change log for ${build.release}:

${promotionRun.changelog}

Change log for the dependency:

${promotionRun.changelog?project=dependency}

Notification backends

Note

The whole list of notification backends is available in the references. You'll find below some detail about the most common ones.

Notification metrics

See the reference