robopigeon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe9a65f475eff9c6c1204035fd2fa3acd934346e59b0562890fa787d70dd63eb
+  data.tar.gz: 62e54d559418f871ffb4e84a6bca22699f036653c75bf0433158fcdeef017d1e
+SHA512:
+  metadata.gz: 19eb5edf119c685f46e81fda2829aae511627d69565a4452f5cad707b955521cf64ff6dd07aa450d7d164605813bd30819ef8547b108c10bd1d636df7a8a7ebc
+  data.tar.gz: 51583e67e7f97a049bc6f92649f34c91caa1aff8ccab8ed4a82b90dea97312e589d04291e881852ec030ebb20b9abd2d5d85a7b3c199c61c4a1de4eb2e24bf22

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Ignore this so that we get up to date stuff.
+Gemfile.lock
+.env
+robopigeon-0.1.0.gem

data/.gitlab-ci.yml

@@ -0,0 +1,27 @@
+.rspec: &rspec
+  stage: test
+  script:
+    - bundle install
+    - ./bin/rspec
+
+stages:
+  - test
+
+Rspec:2.5:
+  <<: *rspec
+  image: ruby:2.5
+
+Rspec:2.3:
+  <<: *rspec
+  image: ruby:2.3
+
+Rspec:2.1:
+  <<: *rspec
+  image: ruby:2.1
+
+Rubocop:
+  image: ruby:2.5
+  stage: test
+  script:
+    - bundle install
+    - ./bin/rubocop

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,65 @@
+AllCops:
+  Exclude:
+    - 'db/**/*'
+    - 'Vagrantfile'
+    - 'vendor/**/*'
+Style/SingleLineBlockParams:
+  Enabled: false
+Style/MultilineBlockChain:
+  Enabled: false
+Metrics/LineLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Documentation:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false
+Style/CommentAnnotation:
+  Enabled: false
+Style/GuardClause:
+  Enabled: false
+Style/EachWithObject:
+  Enabled: false
+Style/ExpandPathArguments:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Naming/AccessorMethodName:
+  Enabled: false
+Style/SignalException:
+  Enabled: false
+Style/RegexpLiteral:
+  Enabled: false
+Style/Next:
+  Enabled: false
+Lint/AssignmentInCondition:
+  Enabled: false
+Style/PercentLiteralDelimiters:
+  Enabled: false
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: false
+Metrics/BlockLength:
+  Enabled: false
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Layout/IndentHeredoc:
+  Enabled: false
+
+# We use this to inject the dsl into the right file
+Security/Eval:
+  Exclude:
+    - 'lib/robopigeon/dsl.rb'
+
+# We use a single class variable to keep track of the documentation across
+Style/ClassVars:
+  Exclude:
+    - 'lib/robopigeon/documentarian.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.5.3

data/.version

@@ -0,0 +1 @@
+0.1.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in robopigeon.gemspec
+gemspec

data/README.md

@@ -0,0 +1,256 @@
+# RoboPigeon
+
+RoboPigeon is here to solve your CI problems. It's a set of tools that you can use to add complexity while simplfying your proccesses.
+
+Some of the things it can do:
+
+Send your team a slack notification when a job fails.
+
+## Sponsors
+
+<a href="https://granicus.com/careers/"><img alt="Granicus" src="https://granicus.com/wp-content/uploads/2018/07/logo.svg"  width="300"></a>
+
+## Installation
+
+This Gem is developed against ruby 2.5, but is tested in CI against the latest versions of `2.1`, `2.3`, and `2.5`
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'robopigeon'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install robopigeon
+
+## Usage
+
+Best way to get started is by running `robopigeon init` and having it write the default robopigeon.rb file.
+
+Then, you can reference the DSL below to make changes to your file.
+
+## DSL Reference:
+- [Helpers](#helpers)
+- [Slack](#slack-1)
+- [GitLab](#gitlab-1)
+
+### Helpers
+
+Helpers can be used anywhere in your config! They're useful for things like looking up someone's slack username to mention it in an email, or looking up who's oncall via pagerduty!
+
+#### Slack
+```ruby
+slack_name_for 'Email or Name'         # slack username just with the @ sign
+slack_user_for 'Email or Name'         # slack message formatted slack user
+slack_user_group 'Group id'            # slack message group mention with an id
+```
+
+#### Git
+```ruby
+git_committer_name                     # name of the person who made the last commit
+git_committer_email                    # email address of the person who made the last commit
+git_merger_name                        # name of the person who made the last merge
+git_merger_email                       # email address of the person who made the last merge
+git_branch_merged_source               # source branch of the last merge
+git_branch_merged_target               # target branch of the last merge
+```
+
+#### GitLab
+```ruby
+deployment_sha 'environment name'      # the current deployed sha for a given environment
+deployment_ref 'environment name'      # the current deploy ref for a given environment
+deployment_shortlog 'environment name' # the shortlog comparison between head and an environment
+```
+
+### Slack
+
+Here's an example of how to use the slack integration!
+
+There are two basic parts of the slack integration, there's the top level with the api_key, bot name, and emoji icon. And the job configuration that let's you select channels, users, and specify the text and attachments.
+
+```ruby
+slack do
+  api_key ENV['SLACK_API_KEY'] # Sets the api key, I like to set it as an env var, defaults to ENV['SLACK_API_KEY']
+  name 'RoboPigeon 9000' # The name that Slack displays in the chat
+  emoji ':robot:' # The emoji icon that the bot uses
+end
+
+job 'super basic' do
+  slack do
+    channel '#testing-slackbots'
+    text 'some information you want to relate'
+  end
+end
+
+job 'mention a user' do
+  slack do
+    channel '#testing-slackbots'
+    text "#{slack_user_for ENV['GITLAB_USER_EMAIL']} did something awesome!"
+  end
+end
+
+job 'test failed' do
+  slack do
+    channel '#testing-slackbots' # A channel to post the message to
+    channel '#testing-more-slackbots' # Another channel to post the message to
+    user 'someone@example.com' # A user that it also sends the message to
+    user 'someone-else@example.com' # Another user that it also sends the message to
+    text "Test on #{ENV['CI_MERGE_REQUEST_SOURCE_BRANCH_NAME']} has failed!"
+    attachment do
+      title 'Website'
+      title_link 'http://alex.ives.mn'
+      pretext 'Here is a button!'
+      color 'danger'
+      # Actions take type, text, url, and style
+      action 'button', 'Website', 'https://alex.ives.mn', 'danger'
+    end
+  end
+end
+
+job 'in a different workspace' do
+  slack do
+    api_key ENV['SLACK_KEY_FOR_SECOND_SPACE']
+    name 'SadBot 9000'
+    emoji ':sad-pigeon:'
+    channel '#testing-slackbots'
+    user 'someone@example.com'
+    text 'Sent to a different workspace'
+  end
+end
+
+job 'with complex attachments' do
+  slack do
+    user ENV['GITLAB_USER_EMAIL']
+    attachment do
+      color 'good'
+      fallback "Stuff is happening! <#{ENV['CI_PIPELINE_URL']}|Pipeline> <#{ENV['CI_PROJECT_URL']}|Project>"
+      action 'button', 'Pipeline', ENV['CI_PIPELINE_URL'], 'primary'
+      action 'button', 'Project', ENV['CI_PROJECT_URL'], 'primary'
+    end
+    attachment do
+      color 'danger'
+      fallback "Stuff is happening! <#{ENV['CI_PIPELINE_URL']}|Pipeline> <#{ENV['CI_PROJECT_URL']}|Project>"
+      action 'button', 'Bad Pipeline', ENV['CI_PIPELINE_URL'], 'danger'
+      action 'button', 'Bad Project', ENV['CI_PROJECT_URL']
+    end
+  end
+end
+```
+
+### GitLab
+
+```ruby
+gitlab do
+  api_url 'https://gitlab.example.com/api/v4' # api endpoint for your gitlab server, defaults to ENV['CI_API_V4_URL']
+  api_key ENV['GITLAB_API_KEY']               # api key for your gitlab server, defaults to ENV['GITLAB_API_KEY']
+end
+
+job 'comment on a merge request' do
+  gitlab do
+    branch ENV['CI_COMMIT_REF_NAME']
+    merge_request_comment 'This comment will appear on all merge requests for the current specified branch'
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at https://gitlab.com/robopigeon/robopigeon.
+
+### Contributors
+
+[Alex Ives](https://alex.ives.mn)
+[Erik Braegelmann](https://gitlab.com/ebraegelmann)
+[Bill Bushey](https://gitlab.com/wbushey)
+
+### History
+
+RoboPigeon grew out of a tool at [Granicus](https://granicus.com) called `gitlab_tools`. As the company grew, the team that created it (the pigeon team) recognized the need for a more flexible tool, and thus robopigeon was born! We also realized that with more flexibility comes more usefulness to other people. Since we get so much from open source, we recognized this as an opportunity to give back.
+
+## Future Development
+
+### Features for 1.0
+
+GitLab
+- [x] Create, comment on, and merge merge requests
+- [x] Get data from the gitlab deployments api as a helper
+- [x] Add helpers to get a list of jira tickets since the provided deployment
+- [x] Create Tag
+- [ ] Create Commits
+
+Semver Helpers
+- [ ] Read a version from a file
+- [ ] Update version files
+
+Slack
+- [x] Post notifications to channels or users
+- [x] Post notifications with url button actions
+- [ ] Post a notification and wait for a threaded response from an authorized user before continuing
+- [ ] Post a notification and wait for a reaction from an authorized user before continuing
+
+Jira
+- [x] Create tickets in jira
+- [x] Transition a ticket between states
+- [x] Comment on tickets
+- [x] Add fix version to ticket
+
+Git
+- [x] Add helpers to get information about changes since the last release
+
+Jenkins
+- [ ] Kick off and monitor a jenkins job until it is completed
+
+Extensions
+- [ ] Create basic example dsl extension gem template
+
+### Features for future version
+
+GitLab
+- [ ] Wait for a merge request to be ready to merge
+- [ ] Kick off a pipeline
+- [ ] Find a pipeline
+- [ ] Wait on a pipeline until completion, failing if the pipeline fails
+- [ ] Push subtree
+- [ ] Create releases
+- [ ] Create Issue
+- [ ] Update issue tags
+- [ ] Assign Issue
+
+GitHub
+- [ ] Create, comment on, and merge pull requests
+- [ ] Create Tag
+- [ ] Create Commits
+- [ ] Create Release
+- [ ] Push subtree
+- [ ] Create Issue
+- [ ] Update issue tags
+- [ ] Assign Issue
+
+Slack
+- [ ] Migrate to block syntax for messages
+
+Changelog
+- [ ] Aggregates changes into log
+- [ ] Helpers provide changes since last deployment
+
+Extensions
+- [ ] Default jobs extension
+- [ ] Jira ticket configuration extension
+- [ ] Slack action template
+
+### Technical Debt
+
+- [x] Document all the dsl methods with RoboPigeon::Documentarian
+- [x] Re-organize code into modules by subject (eg: git, slack, gitlab, jira, ect)
+- [ ] Generate human readable documentation from RoboPigeon::Documentarian

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :generate_docs do
+  require 'robopigeon'
+  File.write('documentation.json', RoboPigeon::Documentarian.generate_docs)
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'robopigeon'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('../bundle', __FILE__)
+
+if File.file?(bundle_binstub)
+  if /This file was generated by Bundler/.match?(File.read(bundle_binstub, 300))
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('../bundle', __FILE__)
+
+if File.file?(bundle_binstub)
+  if /This file was generated by Bundler/.match?(File.read(bundle_binstub, 300))
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+                                           Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('../bundle', __FILE__)
+
+if File.file?(bundle_binstub)
+  if /This file was generated by Bundler/.match?(File.read(bundle_binstub, 300))
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/robopigeon

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'robopigeon'
+
+def usage(bot)
+  bot.usage
+  exit 1
+end
+
+bot = RoboPigeon::Dsl::Root.new
+
+unless ARGV[0]
+  puts 'Missing Job name'
+  usage(bot)
+end
+
+unless bot.job?(ARGV[0])
+  puts "Config does not have job named #{ARGV[0]}"
+  usage(bot)
+end
+
+bot.run(ARGV[0])

data/lib/robopigeon/documentarian.rb

@@ -0,0 +1,39 @@
+require 'json'
+
+module RoboPigeon
+  module Documentarian
+    @@documents = {}
+
+    def self.add_block(name, **options)
+      block_desc = options[:desc]
+      helpers = options[:helpers] || false
+      document = get_document(block: options[:block], document: @@documents)
+      document[name] = {
+        block_desc: block_desc,
+        includes_helpers: helpers
+      }
+      document[name][:params] = options[:params] if options[:params]
+    end
+
+    def self.add_command(name, **options)
+      command_desc = options[:desc]
+      document = get_document(block: options[:block], document: @@documents)
+      document[name] = {
+        command_desc: command_desc
+      }
+      document[name][:params] = options[:params] if options[:params]
+    end
+
+    def self.generate_docs
+      JSON.pretty_generate(@@documents)
+    end
+
+    def self.get_document(**options)
+      block = options[:block]
+      document = options[:document]
+      return get_document(document: document[block.shift], block: block) unless block.empty?
+
+      document
+    end
+  end
+end

data/lib/robopigeon/dsl/helpers.rb

@@ -0,0 +1,17 @@
+RoboPigeon::Documentarian.add_block('helpers', block: [], desc: 'A set of things available to all blocks')
+
+module RoboPigeon::Dsl
+  module Helpers
+    RoboPigeon::Documentarian.add_command(
+      'skip',
+      block: ['helpers'],
+      params: [
+        { name: 'reason', type: 'String', desc: 'reason you want to skip this job', example: 'not configured' }
+      ],
+      desc: 'abort a job that is incomplete, raise an exception with the reason'
+    )
+    def skip(reason)
+      raise SkippedJob, "Job is not complete: #{reason}"
+    end
+  end
+end

data/lib/robopigeon/dsl/initial_jobs.rb

@@ -0,0 +1,36 @@
+module RoboPigeon::Dsl::InitialJobs
+  INITIAL_FILE = "#{File.dirname(__FILE__)}/../resources/initial_robopigeon.rb".freeze
+  # Used to pull in environment variables for things that are mostly set via dsl
+  def base
+    slack do
+      api_key ENV['SLACK_API_KEY']
+    end
+    gitlab do
+      api_url ENV['CI_API_V4_URL']
+      api_key ENV['GITLAB_API_KEY']
+    end
+    job 'version', '-v', 'Show version number' do
+      puts RoboPigeon::VERSION
+    end
+  end
+
+  def init_job
+    jobs['init'] = {
+      desc: 'Initialize a new robopigeon project',
+      action: proc do
+        FileUtils.cp(INITIAL_FILE, RoboPigeon::DEFAULT_FILE)
+      end
+    }
+  end
+
+  def init_help
+    this_job = {
+      desc: 'Show usage information',
+      action: proc do
+        usage
+      end
+    }
+    jobs['help'] = this_job
+    jobs['-h'] = this_job.merge(hidden: true)
+  end
+end

data/lib/robopigeon/dsl/job.rb

@@ -0,0 +1,34 @@
+RoboPigeon::Documentarian.add_block(
+  'job',
+  params: [
+    { name: 'Name', type: 'String', desc: 'Name of the job', example: 'test_job' },
+    { name: 'Description', type: 'String', desc: 'String describing what the job does', example: 'This job tests out some stuff while notifying slack' }
+  ],
+  helpers: true,
+  block: [],
+  desc: 'A grouping of commands to run'
+)
+
+module RoboPigeon::Dsl
+  class Job
+    include RoboPigeon::Dsl::Helpers
+  end
+end
+
+module RoboPigeon::Dsl
+  class Root
+    def job(*args, &block)
+      this_job = {
+        desc: args.pop,
+        action: proc do
+          job = RoboPigeon::Dsl::Job.new
+          job.instance_eval(&block)
+        end
+      }
+      jobs[args.shift] = this_job
+      args.each do |arg|
+        jobs[arg] = this_job.merge(hidden: true)
+      end
+    end
+  end
+end