Workflow Notifications

Workflow Notifications allow you and other members of your team to be notified about the status of your workflow runs. Whether you want to be notified about a Commands, Pipelines, or Services workflow running on your team’s behalf, you can configure notifications to be sent to you and other members of your team via email, Slack, or by commenting on Pull Requests.

To begin configuring notifications for your workflows, navigate to the Settings tab of the Dashboard, then click on the Notifications section in the left-hand navigation menu.

Screenshot of the Workflow Notifications settings screen on the Dashboard.
Screenshot of the Workflow Notifications settings screen on the Dashboard.

Here you’ll find a list of all of the workflow notifications that have been configured for your team (if any), as well as a button to configure new notifications for your team. On this list under the Actions column, you’ll also find buttons to Edit or Delete existing workflow notifications.

Configure a New Notification

Begin configuring a new notification by clicking on the Create Notification Config button in the top-right corner of the screen.

"Create a Notification" modal that appears when you click the "Create Notification Config" button.
"Create a Notification" modal that appears when you click the "Create Notification Config" button.

In the Create a Notification modal that appears, there are several options available to configure, as described below:

Select workflows

Select one or more workflows for which you would like to receive notifications. You can select any combination of Commands, Pipelines, and Services workflows.

Configure Slack recipients

Select one or more Slack channels that should receive notifications when the selected workflows run. The Slack channels available to you will include only those channels that have been configured for your team.

Configure email recipients

Enter one or more email addresses that should receive notifications when the selected workflows run. You can enter any email address, including email addresses that are not associated with your account.

Enable GitHub Pull Request notifications

For workflows that are associated with a Pull Request on GitHub, you can enable notifications to be posted as comments on the Pull Request. To enable this feature, toggle the switch for Pull Request Notifications, then see the configuration section below to configure a workflow to generate these notifications.

Save Notification

After you have configured your desired notification settings, click the Save Notification button to save the configuration and begin receiving notifications.

Configure Pull Request Comment Notifications for a Workflow

To receive notifications as Pull Request comments for a given workflow, you must first define how your workflows are associated with your Pull Requests. This section describes how to configure Pull Request comment notifications for two different types of workflows:

Commands related to a Pull Request
A Commands workflow is related to a Pull Request when the workflow generates Deployment Lifecycle Events that specify the associated repository and branch of the target Pull Request.
Services related to a Pull Request
For a Services workflow to be associated with a Pull Request by our platform, you must configure the workflow to be triggered by a Pull Request event (through your ops.yml file).

Notifications for Commands

Consider a Commands workflow defined by the following ops.yml file example:

version: "1"
  - name: example-command:0.1.0
    description: example workflow run as a command
    run: node /ops/index.js

To associate this workflow with a Pull Request, the Lifecycle Events generated by the workflow must include the repo and branch values of the branch represented by the relevant Pull Request.

For example, the following minimal index.js file simply generates a success Deployment Event that will be associated with the <TARGET_BRANCH> branch of the <ORG_NAME>/<REPO_NAME> repository:

const { ux, sdk } = require('');

async function main() {
    const event = {
        event_name: 'deployment',
        event_action: 'success',

        // Specify the `branch` and `repo` values of the target Pull Request.
        branch: '<TARGET_BRANCH>',
        repo: '<ORG_NAME>/<REPO_NAME>',

        // The `run_id` meta property is required to associate the event
        // with the correct workflow run.
        meta: {
            run_id: process.env.OPS_RUN_ID,
    sdk.track([], event);

main().catch(err => {

Critically, the meta.run_id property of the event must be set to the value of the OPS_RUN_ID environment variable that is automatically set by our platform for every workflow execution. This value is used by our platform to associate the Deployment Event with the correct workflow run.

As usual, the value of the repo property must be in the format <ORG_NAME>/<REPO_NAME>, where <ORG_NAME> is the name of the GitHub organization that owns the repository, and <REPO_NAME> is the name of the repository itself.

Notifications for Services

The configuration necessary for Services workflows to be associated with Pull Requests is defined in the ops.yml file for the relevant workflow. In particular, you must configure the workflow to be triggered by a pull_request event, the definition of which also contain the name of the relevant repository.

ops.yml Excerpt: Event Triggers
  - name: example-service:0.1.0

    . . . # Other config omitted for brevity

      # "github:{repo}:pull_request.{action}" is the format of the event
      - "github:org-name/repo-name:pull_request.opened"
      - build
      - publish
      - start # <-- This is the critical trigger action.

    . . .

As you can see in the above example, the events field of the Services workflow configuration specifies an event trigger in the standard format of {origin}:{repo}:{event}. In this case, the origin is github, the repo is the path the repository on GitHub in the format <ORG_NAME>/<REPO_NAME>, and the event is a type of pull_request.* event.

For the full list of pull_request.* actions that can be used to trigger a workflow, see our list of Supported Events from GitHub.

Full-Qualified Event Trigger Names
Please note that triggers in the events list of a workflow’s configuration must always be specified in its full form. Any wildcard characters (e.g. *) you may find in our docs are for brevity only, and will not work if used in the ops.yml file for an actual workflow.

When the start trigger of a Services workflow is run as a result of a pull_request.* event, the workflow execution will be automatically associated with the Pull Request that triggered the event in the first place.

Highlight Personal Notifications

Notifications for workflows on the platform are configured on a per-team basis, which means that you may see notification configurations listed on the Dashboard which are not relevant to you. To help you quickly identify the notifications for which you are personally configured to receive notifications, we display irrelevant notifications in a muted color.

This visual filtering can be toggled on and off by clicking the Show My Notifications switch on the Notifications settings screen. When this feature is toggled on, any notifications for which your email address is not configured to receive notifications will be dimmed.