Skip to main content

Notifications YAML

This page specifies the YAML syntax and rules for notifications on Semaphore.

Overview​

Use this reference in conjunction with the Semaphore Command Line to manage and configure notifications on Semaphore.

Notifications can be sent only when a pipeline is finished.

apiVersion​

Defines the version of the YAML syntax for this file.

The only supported value is: v1alpha

kind​

Defines the type of resource.

For notification resources use the kind: Notification

metadata​

Defines metadata about the notification.

Supports the following properties:

name​

A string defining the name of the notification.

id​

A unique identifier populated by Semaphore. It should not be modified.

create_time​

The notification creation time in UNIX epoch format. Automatically populated by Semaphore.

update_time​

The last notification update time in UNIX epoch format. Automatically populated by Semaphore.

spec​

The spec property holds a list of notification rules

rules​

Notifications must have at least one rule. Semaphore evaluates the rule in the order defined and triggers the notification when a match is found.

This property contains:

name​

A string defining the name of the rule.

filter​

Specifies conditions for the notification to trigger. It consists of a list of rules. For every rule that matches, Semaphore sends a notification using the notify properties specified for that rule.

Each item list in filter contains the following properties:

For a filter to match, all its properties must be evaluated to true. If any of the properties have multiple values, at least one of these must match.

note

You can use regular expressions by wrapping the filtering properties values in slashes, e.g. /^dev.*/

projects​

Mandatory property. Contains a list of project names where the notification rule applies.

branches​

Optional property. Contains a list of Git branches. If specified, the rule can only trigger events that apply to one of the listed branches.

pipelines​

Optional property. A list of pipeline filenames. If specified, the rule can only trigger events originating from one of the listed pipelines.

notify​

Specifies how to send the notification.

This property may contain these sub-properties:

  • slack: configuration to send Slack notifications
  • webhook: configuration to send notifications to webhook-enabled services

slack​

Specifies how to send a notification to Slack.

Supports the following properties:

endpoint​

Mandatory property. Specifies the URL for the Slack Incoming WebHook.

See Incoming WebHooks for more information on configuring the URL.

note

It is not possible to override the channel configuration for a given webhook. Each webhook is restricted to notify the configured channels or users.

channels​

A list of Slack channels or users. Channels begin with the hash (#) symbol and users with the at (@) symbol.

This property is optional. If not specified, the notification is sent to the default channel associated with the webhook.

webhook​

Specifies how to send notifications to webhook-enabled services.

Supports the following properties:

endpoint​

Mandatory property. Specifies the URL to contact to send the notification.

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

action​

Defines the HTTP method to use for sending the notification.

This property is optional and defaults to POST.

timeout​

Defines the timeout for the notification request expressed in milliseconds. The value must be between 1 and 1000.

This property is optional and defaults to 500.

secret​

An optional property used to sign the notification payload. This property is the name of an organization-level secret.

If this property is not provided, the notification payload is not signed.

Examples​

The following example has two rules:

  1. Sends a Slack notification to the #devops channel and to the user #mtsukalos on events related to the "API-docs" project
  2. Sends a signed notification to a webhook-enabled service on the following conditions:
    • Project name is "website", "docs", or matches regexp "/.*api$/"
    • Branch is "master" or matches regexp "/^feature-.*/"
    • Pipeline is "semaphore.yaml" (default pipeline)
Example
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

See Also​