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 CTO.ai Dashboard, then click on the Notifications section in the left-hand navigation menu.

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.

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

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"
commands:
  - 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('@cto.ai/sdk');

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 => {
    sdk.log(err);
    process.exit(1);
});

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.

services:
  - name: example-service:0.1.0

    . . . # Other config omitted for brevity

    events:
      # "github:{repo}:pull_request.{action}" is the format of the event
      - "github:org-name/repo-name:pull_request.opened"
    trigger:
      - 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.

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 CTO.ai platform are configured on a per-team basis, which means that you may see notification configurations listed on the CTO.ai 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.