codebuild-notifier 0.2.0

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,261 @@
+# 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 <a href="https://api.slack.com/apps">https://api.slack.com/apps</a>
+- 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 (<a href="#secret-in-aws-secrets-manager">see below</a>)
+
+*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:
+
+```ruby
+  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:
+```json
+{
+  "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
+
+```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
+
+```yml
+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
+
+```yml
+phases:
+  post_build:
+    commands:
+      - update-build-status --slack-admin-usernames="fred,velma"
+```
+
+### Options
+
+<table>
+  <tr>
+    <th>ENV var</th>
+    <th>command-line</th>
+    <th>Default value</th>
+    <th>Notes</th>
+  </tr>
+  <tr>
+    <th>
+      CBN_ADDITIONAL_CHANNEL
+    </th>
+    <td>
+      <nobr>--additional-channel</nobr>
+    </td>
+    <td>
+      not set
+    </td>
+    <td>
+      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.
+    </td>
+  </tr>
+  <tr>
+    <th>
+      CBN_AWS_REGION
+    </th>
+    <td>
+      <nobr>--region</nobr>
+    </td>
+    <td>
+      value of AWS_REGION env var in CodeBuild container
+    </td>
+    <td>
+      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.
+    </td>
+  </tr>
+  <tr>
+    <th>
+      CBN_DYNAMO_TABLE
+    </th>
+    <td>
+      <nobr>--dynamo-table</nobr>
+    </td>
+    <td>
+      branch-build-status
+    </td>
+    <td>
+      This table must be created and permissions granted to it as described
+      in <a href="#infrastructure-requirements">Infrastructure Requirements</a>
+    </td>
+  </tr>
+  <tr>
+    <th>
+      CBN_SLACK_ADMIN_USERNAMES
+    </th>
+    <td>
+      <nobr>--slack-admin-usernames</nobr>
+    </td>
+    <td>
+      not set
+    </td>
+    <td>
+      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.<br />
+      Separate multiple values with commas, with no spaces.<br />
+      e.g. fred,velma
+    </td>
+  </tr>
+  <tr>
+    <th>
+      CBN_SLACK_SECRET_NAME
+    </th>
+    <td>
+      <nobr>--slack-secret-name</nobr>
+    </td>
+    <td>
+      slack/codebuild
+    </td>
+    <td>
+      The name of a secret in AWS Secrets Manager with the app or bot auth token.
+    </td>
+  </tr>
+  <tr>
+    <th>
+      CBN_WHITELIST_BRANCHES
+    </th>
+    <td>
+      <nobr>--whitelist-branches</nobr>
+    </td>
+    <td>
+      master,release
+    </td>
+    <td>
+      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.<br />
+      Separate multiple values with commas, without spaces.<br />
+      e.g. 'master,nightly,jira-50012'
+    </td>
+  </tr>
+</table>

data/bin/update-build-status

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+
+# codebuild-notifier
+# Copyright © 2018 Adam Alboyadjian <adam@cassia.tech>
+# Copyright © 2018 Vista Higher Learning, Inc.
+#
+# codebuild-notifier is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either
+# version 3 of the License, or (at your option) any later version.
+#
+# codebuild-notifier is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with codebuild-notifier.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'codebuild-notifier'
+require 'optparse'
+# This script updates a DynamoDb table with the last codebuild build status
+# for the current project and branch or pr. If the current build status is
+# different from the previous status, the email address of the author of the
+# last commit is extracted from the git commit, and a notification is sent
+# via slack.
+
+def quit(message)
+  cb_puts(message)
+  exit
+end
+
+def cb_puts(message)
+  puts "CODEBUILD NOTIFIER: #{message}"
+end
+
+def not_latest_commit_in_branch_message(build, config)
+  "Commit #{build.commit_hash} in project #{build.project_code} did " \
+  'not match the most recent commit for any Pull Requests or the ' \
+  "whitelisted branches: #{config.whitelist}. Skipping status updates."
+end
+
+def not_pr_or_whitelisted_branch_message(config)
+  'Build is neither for a Pull Request nor for one of whitelisted ' \
+  "branches: #{config.whitelist}. Skipping status updates."
+end
+
+def no_status_diff_message(build)
+  "Current status #{build.status} is same as last status. " \
+  'Skipping slack notifications.'
+end
+
+command_line_opts = {}
+
+# rubocop:disable Metrics/BlockLength
+OptionParser.new do |opts|
+  opts.banner = 'Usage: update-build-status [OPTIONS]'
+
+  opts.on(
+    '--additional-channel=CHANNEL',
+    'status notifications for whitelisted branches will be sent here ' \
+    'as well as to author/committer'
+  ) { |usernames| command_line_opts[:slack_admin_users] = usernames }
+
+  opts.on(
+    '--slack-admin-usernames=USERS',
+    'comma-separated list of slack users to be notified if build status ' \
+    'notifications fail to send'
+  ) { |usernames| command_line_opts[:slack_admin_users] = usernames }
+
+  opts.on(
+    '--dynamo-table=TABLE',
+    'table for storing build statuses'
+  ) { |table| command_line_opts[:dynamo_table] = table }
+
+  opts.on(
+    '--slack-secret-name=SECRET',
+    'name of Secrets Manager secret with slack app/bot auth token'
+  ) { |slack_secret| command_line_opts[:slack_secret_name] = slack_secret }
+
+  opts.on(
+    '--whitelist-branches=BRANCHES',
+    'comma-separated list of branches that will have build notifications ' \
+    'sent even if there is no open Pull Request'
+  ) { |whitelist| command_line_opts[:whitelist_branches] = whitelist }
+
+  opts.on('--region=REGION', 'AWS region') do |region|
+    command_line_opts[:region] = region
+  end
+end.parse!
+# rubocop:enable Metrics/BlockLength
+
+config = CodeBuildNotifier::Config.new(command_line_opts)
+build = CodeBuildNotifier::CurrentBuild.new
+history = CodeBuildNotifier::BuildHistory.new(config, build)
+
+last_build = history.last_entry
+
+if build.launched_by_retry?
+  # Whenever a build is triggered by a PR or whitelisted branch, we update
+  # the record for that trigger with the commit hash. If a build is then
+  # launched using Retry, the status is updated and are notifications sent
+  # only if the re-tried build was for the latest commit. Otherwise re-trying
+  # an older commit could result in inaccurate notifications.
+  quit(not_latest_commit_in_branch_message(build, config)) unless last_build
+
+  source_id = last_build.source_id
+  source_ref = last_build.source_ref
+else
+  # We only want to track information for whitelisted branches and branches
+  # with open Pull Requests.
+  unless config.non_pr_branch_ids.include?(build.trigger) || build.for_pr?
+    quit(not_pr_or_whitelisted_branch_message(config))
+  end
+  source_id = build.source_id
+  source_ref = build.trigger
+end
+
+# Update record for this project + branch/pr in DynamoDb even if the
+# status hasn't changed, so the latest commit hash is stored.
+history.write_entry(source_id) do |new_item|
+  cb_puts "Updating dynamo table #{config.dynamo_table} with: #{new_item}"
+end
+
+quit(no_status_diff_message(build)) if last_build&.status == build.status
+
+slack_message = CodeBuildNotifier::SlackMessage.new(build, config, source_ref)
+sender = CodeBuildNotifier::SlackSender.new(config)
+sender.send(slack_message)

data/codebuild-notifier.gemspec

@@ -0,0 +1,50 @@
+# codebuild-notifier
+# Copyright © 2018 Adam Alboyadjian <adam@cassia.tech>
+# Copyright © 2018 Vista Higher Learning, Inc.
+#
+# codebuild-notifier is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either
+# version 3 of the License, or (at your option) any later version.
+#
+# codebuild-notifier is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with codebuild-notifier.  If not, see <http://www.gnu.org/licenses/>.
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'codebuild-notifier/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'codebuild-notifier'
+  spec.version     = CodeBuildNotifier::VERSION
+  spec.authors     = ['VHL Ops Team']
+  spec.email       = ['ops@vistahigherlearning.com']
+  spec.summary     = 'Slack notifications for CodeBuild jobs.'
+  spec.description = 'CodeBuild Notifier tracks the past status of CI jobs ' \
+                     'run on AWS CodeBuild for each pr or whitelisted branch' \
+                     'for a given project, and sends slack notifications ' \
+                     'when a branch/pr changes build status.'
+  spec.homepage    = 'https://github.com/vhl/codebuild-notifier'
+  spec.executables = ['update-build-status']
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |file|
+    file.match(%r{^(test|spec|features)/})
+  end
+
+  spec.add_dependency 'activesupport', '> 2.0', '< 6.0'
+  spec.add_dependency 'aws-sdk-dynamodb', '~> 1.16'
+  spec.add_dependency 'aws-sdk-secretsmanager', '~> 1.19'
+  spec.add_dependency 'hashie', '> 1.0', '< 4.0'
+  spec.add_dependency 'slack-ruby-client', '~> 0.13'
+
+  spec.add_development_dependency 'rspec', '~> 3.8'
+  spec.add_development_dependency 'rubocop', '0.58.2'
+  spec.add_development_dependency 'rubocop-rspec', '1.30.0'
+  spec.add_development_dependency 'simplecov', '~> 0.16'
+end

data/lib/codebuild-notifier.rb

@@ -0,0 +1,24 @@
+# codebuild-notifier
+# Copyright © 2018 Adam Alboyadjian <adam@cassia.tech>
+# Copyright © 2018 Vista Higher Learning, Inc.
+#
+# codebuild-notifier is free software: you can redistribute it
+# and/or modify it under the terms of the GNU General Public
+# License as published by the Free Software Foundation, either
+# version 3 of the License, or (at your option) any later version.
+#
+# codebuild-notifier is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with codebuild-notifier.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'codebuild-notifier/config'
+require 'codebuild-notifier/build_history'
+require 'codebuild-notifier/current_build'
+require 'codebuild-notifier/git'
+require 'codebuild-notifier/slack_message'
+require 'codebuild-notifier/slack_sender'
+require 'codebuild-notifier/version'