Managing Your CI/CD Build Notifications

Notifications Overview

As a default, we’ve setup a notification rule that sends an email to everyone on the team, whenever something happens to the builds in the project, regardless of branch.

Notification rules are grouped by branch, or branches, and you can setup as many as you like. Each rule applies to one service, so, for example, if you want to send the same notification to two Slack channels, you’ll have to setup two rules.

Each group can apply to a specific branch, e.g. master, or multiple branches that match a pattern, e.g. feature/*.

Notifications

Branch Matching

If you use the wildcard * in the branch name, it will try and match to multiple branches. Let’s say you have a naming convention for your feature branches that start with feature followed by some name, you could create a notification rule that matches all feature branches by specifying feature/* as the branch name.

The wildcard allows you to replace any amount of characters, so you could even do *design*feature* to match any branch that have those two words in it.

Integrated Notification Services

We have support for the following services:

Campfire
Email Notification
Slack
Webhook

If the service you’re looking for isn’t on the list, you might be able to use the webhook option.

Configuring Build Notifications

To configure build notifications, go to your Project Settings and then click into the Notifications tab.

If you want to add more rules to an existing branch (or branch match) click the add button to the right of the branch name. If you want to add rules for a new branch (or branch match) click the big new notification button at the bottom of the page.

In case you no longer want to have a specific rule trigger notifications, you can either disable it (use the toggle on the right hand side) or delete it completely.

Note: Each service has different detail fields that will need to be populated, so refer to the sections below to see which apply for the service you want to configure.

Common Configuration

All rules apply to either "All Branches", a names branch, or a branch match. If the field is left empty, the rule will apply to all branches.

Additionally, all rules can select between started, failed, succeeded, and recovered as events that trigger a notification. You must select at least one event in order to save the rule.

started → sends a notification when a new build is triggered
failed → sends a notification if a build fails or is stopped for some reason
succeeded → sends a notification if the build finishes successfully
recovered → sends a notification if the branch’s current build finishes successfully, recovering from the failure of the branch’s prior build. Note: does not trigger when using Restart Build from the console.
requires approval → sends a notification if a build is paused pending a manual approval

Campfire

For Campfire, we need both an API key and your domain name (just the first part, without .campfirenow.com) as well as the specific room you want the notifications to end up in.

Email Notification

For an email rule, you can select whether all members of the project will receive notifications, or only the person whos commit triggered the build.

If only the committer should be notified, either the emails or usernames must be the same in both CodeShip and GitHub/Bitbucket/GitLab. If they’re different, no notifications are sent.

Disable Email

If you don’t want to receive any emails you can set that on your account page. This applies to all emails though, and not just for one project.

Not Receiving Email

If you are not receiving email notifications, but are expecting them, there are a few things to check. First make sure notifications are enabled for your account. Next make sure that the email address on your CodeShip account matches the email you have set in your Git configuration on your local machine. You can check this with:

git config --get user.email

If all those settings look correct and you are still not receiving notifications, please contact us and we can further investigate.

Slack

For Slack, the only thing you need is the webhook URL Slack provides when you configure a CodeShip integration. Copy the URL to the webhook URL field.

Webhook

Webhooks allows for a range of custom integrations. It’s pretty similar to the other services in terms of setup though, as you just need to provide the URL of the webhook we’ll need to call.

Webhook Payload

When sending the notification to a webhook, we send a HTTP POST request containing the following build data:

project_full_name is deprecated and will be removed in the future

{
  "build": {
    "build_url":"https://www.codeship.com/projects/10213/builds/973711",
    "commit_url":"https://github.com/codeship/docs/commit/96943dc5269634c211b6fbb18896ecdcbd40a047",
    "project_id":10213,
    "build_id":973711,
    "status":"initiated",
    "project_full_name":"codeship/docs",
    "project_name":"codeship/docs",
    "commit_id":"96943dc5269634c211b6fbb18896ecdcbd40a047",
    "short_commit_id":"96943",
    "message":"Merge pull request #34 from codeship/feature/shallow-clone",
    "committer":"beanieboi",
    "branch":"master"
  }
}▼

The status field can have one of the following values:

initiated for newly started build
error for failed builds
success for passed builds
stopped for stopped builds
waiting for waiting builds
ignored for builds ignored because the account is over the monthly build limit
blocked for builds blocked because of excessive resource consumption
infrastructure_failure for builds which failed because of an internal error on the build VM

Custom notifications with CloudBees CodeShip Pro

Due to CloudBees CodeShip Pro’s unique architecture, you have more flexibility in implementing custom notifications via your codeship-steps.yml file.

In addition to using the above webhooks method, you can also define custom steps in your build pipeline to push notifications via methods not otherwise supported by CodeShip.

The Notification Script

To look at using your CloudBees CodeShip Pro pipeline for flexible, custom notifications we will review a simple Slack script as a custom notification method.

First of all, we can create a simple notification script, pulling all configuration and credentials from environment variables, or mounted volumes should we need to use build artifacts.

#!/bin/sh
# Post to Slack channel on new deployment
# https://api.slack.com/incoming-webhooks

# script available at: https://github.com/codeship/scripts/blob/master/notifications/slack.sh

# You can either add those here, or configure them on the environment tab of your
# project settings.

SLACK_WEBHOOK_TOKEN=${SLACK_WEBHOOK_TOKEN:?'You need to configure the SLACK_WEBHOOK_TOKEN environment variable!'}
SLACK_BOT_NAME=${SLACK_BOT_NAME:="CodeShip Bot"}
SLACK_ICON_URL=${SLACK_ICON_URL:="https://d1089v03p3mzyq.cloudfront.net/assets/website/logo-dark-90f893a2645c98929b358b2f93fa614b.png"}
SLACK_MESSAGE=${SLACK_MESSAGE:?"${CI_COMMITTER_USERNAME} just deployed version ${CI_COMMIT_ID}"}

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "'"${SLACK_BOT_NAME}"'",
  "text": "'"${SLACK_MESSAGE}"'",
  "icon_url": "'"${SLACK_ICON_URL}"'"}' \
  https://hooks.slack.com/services/$SLACK_WEBHOOK_TOKEN▼

Integrating the Notification Script

It’s quite simple to integrate a simple script like this into the deployment pipeline. First we can build it into a standalone container, or use an existing one from elsewhere in the pipeline which has the deploy script added to it.

# Dockerfile.notify
FROM ubuntu

RUN apt-get install -y curl

COPY ./slack ./▼

We’ll need to provide this container with the necessary environment variables. The standard CI_* variables will be provided automatically, however we’ll need to provide the SLACK_WEBHOOK_TOKEN. This can be safely injected via the encrypted_env_file service declaration, and the encryption commands. By encrypting this environment variable, and adding it to our repository, it can be later decoded and provided to our notifications container.

deploynotify:
  build:
    image: myuser/myrepo-deploynotify
    dockerfile: Dockerfile.notify
  encrypted_env_file:
    - deploy.env.encrypted▼

By adding a relevant step to the steps file, we can control under what conditions this notification fires.

- service: deploynotify
  command: ./slack
  tag: master▼

Other Integrations With CloudBees CodeShip Pro

Since you can integrate any container you wish into your pipeline, there are no limitations on what notifications you can use. In our scripts repo, you can see other examples of custom notifications.

Other Ways to Get Notified

GitHub, Bitbucket and GitLab Status API

We will automatically use the status API for pull requests on GitHub, Bitbucket and GitLab. This does not need to be explicitly enabled, although it can be disabled via the General settings of your project.

Status Badges On Your Repo

If you want to add a badge showing your last builds status to your README, you can find the code in the General settings of your project.

The raw URL for the image looks like the this:

https://codeship.com/projects/YOUR_PROJECT_UUID/status?branch=BRANCH_NAME

The UUID for a specific project is also available on the General tab in your project settings.