Skip to content

Latest commit

 

History

History
238 lines (167 loc) · 7.75 KB

notifications-yaml-reference_5be45bb02c7d3a31944dbc98.md

File metadata and controls

238 lines (167 loc) · 7.75 KB
Raw

Overview

This document is the reference to 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.

The list of values for apiVersion: v1alpha.

kind

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

The list of values for kind: Notification.

metadata

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

name

The value of the name property in the metadata context, which is a string, defines the name of the notification. 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 among all notifications. 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 of creation of the notification.

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 last time the notification was altered.

spec

The spec property holds the 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 in a rules property.

name

The value of the name property, which is a string, in the metadata context defines the name of the notification rule.

filter

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

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 (.*) would 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 the list of the Semaphore 2.0 projects that interest us.

The projects property is mandatory.

branches

The branches property holds a list of strings, which should be the GitHub branch names that interest us.

The branches property is optional.

pipelines

The pipelines property is used for holding the list of the pipeline filenames that interest us.

The pipelines property is optional.

notify

The notify property holds the slack property.

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 visiting Incoming WebHooks.

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: you can use just a single Incoming WebHook from Slack for all your notifications as this Incoming WebHook has access to all the channels of a Slack Workspace.

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.

An example

The following YAML code present 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:
      slack:
        endpoint: https://hooks.slack.com/services/XXTXXSSA/ABCDDAS/XZYZWAFDFD
        channels:
        - '#engineering'
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 of the notification specifies a single project name that is called API-docs. All notifications will go to the #devops channel and to the mtsoukalos user using the specified Incoming WebHook of Slack. In this case the Slack channel associated with the specified Incoming WebHook will be ignored.

The second rule is more complex than the first one. The values of the projects property specify two exact project names named 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 one is an exact match to the master branch.

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

Once these three filters are evaluated to true, the rule will send a notification to the #engineering channel. Once again, the Slack channel associated with the specified Incoming WebHook will be ignored.

Please note that the status property at the end is not currently being used.

You can find out how to create new notifications by visiting the Slack Notification and the sem command line tool Reference pages of the Semaphore 2.0 documentation.

See Also