codebuild-notifier

Reports status of AWS CodeBuild CI jobs to slack.

Infrastructure Requirements

Slack App or Bot in your workspace

Notifications will be sent as slack Direct Messages to users from the default Slack bot in your workspace (e.g. @slackbot)

• Go to https://api.slack.com/apps
• Create a New App, e.g. App Name: CodeBuild Notifier
• Under Add features and functionality select "Permissions" and grant these scopes:
  • chat:write:bot
  • users:read
  • users:read.email
• Click Install App To Workspace and store the OAuth token generated in a new secret in AWS Secrets Manager (see below)

Optional Add a Bot User to your app - instead of the default Slack bot, messages will come from a user with a name you choose, e.g. CodeBuildBot

• Under Features / Bot Users, click Add a Bot User
• Select a name and display name; the always show as online option does not matter
• After adding the Bot User, re-install the app to your workspace
• A new OAuth token will be generated specific to the Bot User. Store this in AWS Secrets Manager instead of the App token.

DynamoDB table

• expected to be named 'branch-build-status', but can be configured
• the following definition:

  AttributeDefinitions [
    { AttributeName: 'source_id', AttributeType: 'S' },
    { AttributeName: 'commit_hash', AttributeType: 'S' }
  ]
  GlobalSecondaryIndexes [
    {
      IndexName: 'commit_hash_index',
      KeySchema: [
        { AttributeName: 'commit_hash', KeyType: 'HASH' }
      ],
      Projection: { ProjectionType: 'ALL' },
    }
  ]
  KeySchema [
    { AttributeName: 'source_id', KeyType: 'HASH' }
  ]

Secret in AWS Secrets Manager

• expected to be named 'slack/codebuild', but can be configured
• contents should be: json { "token": "xoxo-your-slack-app-token" }

IAM Service Role for CodeBuild projects

You will likely already have a service role granting CloudWatch access, to which you will want to add the following, substituing your region, account id, and if different, dynamo table name and secrets-manager secret name:

{
  "Action": [
    "dynamodb:BatchGetItem",
    "dynamodb:GetItem",
    "dynamodb:PutItem",
    "dynamodb:Query",
    "dynamodb:Scan",
    "dynamodb:UpdateItem"
  ],
  "Effect": "Allow",
  "Resource": [
    "arn:aws:dynamodb:<your-region>:<your-account-id>:table/branch-build-status",
    "arn:aws:dynamodb:<your-region>:<your-account-id>:table/branch-build-status/*"
  ]
},
{
  "Action": "secretsmanager:GetSecretValue",
  "Effect": "Allow",
  "Resource": [
    "arn:aws:secretsmanager:<your-region>:<your-account-id>:secret:slack/codebuild*"
  ]
}

Configuration

Installation

Pre-requisites

The base docker image used for your CodeBuild project must include ruby, or you must install it using the project's buildspec.yml file. Any ruby from 2.3.x to 2.5.x will work.

Using buildspec

Add to the install: phase of your buildspec.yml

phases:
  install:
    commands:
      - gem install codebuild-notifier

Using custom Docker image

Add to your Dockerfile

RUN gem install codebuild-notifier

Usage

Add to the post_build: phase of your buildspec.yml file

phases:
  post_build:
    commands:
      - update-build-status

Configuration

ENV vars

ENV vars can either be set in Dockerfile e.g.

ENV CBN_SLACK_ADMIN_USERNAMES scooby,shaggy

Or in buildspec.yml

env:
  variables:
    CBN_SLACK_ADMIN_USERNAMES: 'fred,velma'

command-line

In buildspec.yml

phases:
  post_build:
    commands:
      - update-build-status --slack-admin-usernames="fred,velma"

Options

ENV var	command-line	Default value	Notes
CBN_ADDITIONAL_CHANNEL	--additional-channel	not set	If whitelist branches are set, status notifications for these branches can be sent to this channel, as well as direct messages to the author/committer of the commit triggering the build.
CBN_AWS_REGION	--region	value of AWS_REGION env var in CodeBuild container	If for some reason the dynamo table and secrets-manager live in a different region than where CodeBuild is executing, you can specify that region.
CBN_DYNAMO_TABLE	--dynamo-table	branch-build-status	This table must be created and permissions granted to it as described in Infrastructure Requirements
CBN_SLACK_ADMIN_USERNAMES	--slack-admin-usernames	not set	If no slack user can be found in your workspace with the email address of the author or committer of a commit, a message will be sent to the slack usernames specified. Separate multiple values with commas, with no spaces. e.g. fred,velma
CBN_SLACK_SECRET_NAME	--slack-secret-name	slack/codebuild	The name of a secret in AWS Secrets Manager with the app or bot auth token.
CBN_WHITELIST_BRANCHES	--whitelist-branches	master,release	Normally statuses will be stored and notifications sent only for builds triggered by commits to branches with open Pull Requests. However, it can be useful to get notifications for all commits to certain branches, regardless of Pull Request status. Separate multiple values with commas, without spaces. e.g. 'master,nightly,jira-50012'