Notifications YAML Reference#

This document is the reference for the YAML grammar used for describing notifications and specifying notification rules.

Notifications can be sent only when a pipeline is finished, either successfully or unsuccessfully. Additionally, you will need the sem command line tool in order to work with notifications.

Properties#

apiVersion#

The apiVersion property defines the version of the YAML grammar that will be used in the current YAML file. Different versions might have different features.

Here is a list of values for the apiVersion property: v1alpha.

kind#

The kind property defines the purpose of a YAML file. For a YAML file that will be used for defining notifications, the value for the kind property should be Notification.

Here is a list of values for the kind property: Notification.

metadata#

The metadata property defines the metadata of a Notifications YAML file and supports the name, id, create_time, and update_time properties.

name#

The value of the name property, which is a string, defines the name of a notification in the context of metadata. This is what will appear when you execute the sem get notifications command.

id#

The value of the id property is automatically generated and assigned by Semaphore 2.0 and is unique to each notification. It should not be edited.

create_time#

The value of the create_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time that the notification was created.

update_time#

The value of the update_time property is automatically generated by Semaphore 2.0 and is in the UNIX epoch format. It holds the time the notification was last altered.

spec#

The spec property holds a list of notification rules.

rules#

Each rules property holds the definition of a notification rule.

In order to define a notification, you will need to have at least one rules item.

The rules property in more detail#

In this section, we are going to explain the properties that are used by the rules property.

rule name#

The value of the name property, which is a string, defines the name of each notification rule.

filter#

The filter property holds the projects, branches, and pipelines properties. The projects property is the only one of these that is mandatory.

The values of branches, projects, and pipelines properties can contain regular expressions. Regex matches must be wrapped in forward slashes (/.-/). Specifying a branch/project/pipeline name without slashes (.-) will execute a direct equality match.

For a filter to be true, each one of its properties should be true. If a property such as branches has multiple values, at least one of these values should be true for the entire property to be true.

The filter property holds the logic of the notification rule.

projects#

The projects property is used for holding a list of Semaphore 2.0 projects that you have selected.

The projects property is mandatory.

branches#

The branches property holds a list of strings, which should be the Git branch names that you have selected.

The branches property is optional.

pipelines#

The pipelines property is used for holding a list of the pipeline filenames that you have selected.

The pipelines property is optional.

notify#

The notify property holds the slack and webhook properties.

slack#

The slack property holds the endpoint and channels properties.

endpoint#

The endpoint property holds the URL of the Incoming WebHook that will be used. Incoming WebHooks offer a simple way for posting messages from external sources into Slack.

You can learn more about defining the value of the endpoint property by reading Slack's Incoming WebHooks documentation.

Please note that if a notification does not work as expected, you might want to begin the debugging process by verifying the Slack WebHook used.

Tip: It is not possible to override and add more Slack channels into the payload. You have to configure one WebHook per channel.

The endpoint property is mandatory.

channels#

The channels property holds a list of strings. Each string item is the name of a Slack channel or the name of a Slack user. Slack channels begin with a # character and Slack users begin with a @ character.

A notification can send a message to multiple Slack channels and/or multiple users.

The channels property is optional. When the channels property is not defined, all notifications go to the default channel associated with the Incoming WebHook used.

webhook#

The webhook property holds the endpoint, action, timeout, and secret properties.

endpoint#

The endpoint property holds the URL to which Semaphore will send the notification.

You can learn more about payload of a notification in our Webhook Notification documentation.

The endpoint property is mandatory.

action#

The action property holds the HTTP method used to send a notification.

The action property is optional, and its default value is POST.

timeout#

The timeout property holds the delivery timeout in ms. This value must be from 1 to 1000 (ms).

The timeout property is optional, and its default value is 500.

secret#

The secret property holds the name of Semaphore's Secret which will be used to sign the payload.

The secret property is optional, and its default value is empty string, in that case payload won't be signed.

An example#

The following YAML code shows an example of a notification as returned by the sem get notification [name] command:

$ sem get notifs docs
apiVersion: v1alpha
kind: Notification
metadata:
  name: docs
  id: 2222f08c-93f9-459b-8825-ab8be49c9d19
  create_time: "1542024088"
  update_time: "1542280192"
spec:
  rules:
  - name: Send notifications for docs project
    filter:
      projects:
      - API-docs
    notify:
      slack:
        endpoint: https://hooks.slack.com/services/XXTXXSSA/ABCDDAS/XZYZWAFDFD
        channels:
        - '#devops'
        - '@mtsoukalos'
  - name: On finished pipelines for S1, docs, or .*-api projects
    filter:
      projects:
      - website
      - /.*-api$/
      - docs
      branches:
      - /^feature-.*/
      - master
      pipelines:
      - semaphore.yml
    notify:
      webhook:
        endpoint: https://example.org/postreceiver
        secret: docs-notification-secret
status: {}

This notification has two rules, one named Send notifications for docs project and another named On finished pipelines for S1, docs, or .*-api projects.

The first rule specifies a single project name: API-docs. All notifications for this project will go to the #devops channel and to the mtsoukalos user using the specified Slack Incoming WebHook. In this case, the Slack channel associated with the specified Incoming WebHook will be ignored.

The second rule is more complex than the first. The values of the projects property specify two project names, website and docs, as well as a regular expression (/.*-api$/) that will be evaluated against all the project names of the current organization. For this filter to be true, at least one of the matches must be true.

Similarly, the branches property has two items. The first one is a regular expression that matches all branches that begin with the feature string and the second is an exact match to the master branch.

Next, specify in the pipelines filter that you are only interested in the main pipeline, which always begins with the semaphore.yml file.

Once these three filters are evaluated to be true, the rule will send a notification to the https://example.org/postreceiver URL.

Please note that the status property at the end is not currently in use.

You can find out how to create new notifications by visiting our Slack Notification, Webhook Notification, and sem command line tool reference documentation.

See Also#