rails-approvals

Rails::Approvals

Add approval processes for Rails console access, running database migrations, and more in production. Be notified of approval requests and respond to them directly in Slack.

Installation

Rails::Approvals requires a Slack application installed in your Slack workspace. The Slack application gives Rails::Approvals the ability to post approval requests to your configured Slack channel and other workspace users can respond to approval requests.

This guide will walk you through the process of installing the gem, configuring Slack, and rails-approvals to meet your needs.

Install the rails-approvals gem

First, you must add the following line to your application's Gemfile to install rails-approvals:

gem 'rails-approvals'

And then execute:

$ bundle

Or add it rails-approvals automatically to your Gemfile with:

$ bundle add rails-approvals

Create Slack application

Now that you have the gem installed, it's time to create the Rails Approvals Slack application for your Slack workspace. To create a Slack application you must be a Slack workspace administrator.

Using the link below a new Slack application will be prefilled with all settings and scopes required for Rails::Approvals to work. Slack will prompt you to verify the permissions that will be granted before you create the Slack application.

Later in this installation guide you will be instructed to configure the webhook URL that Rails::Approvals needs to handle approval request responses within Slack's settings.

If you'd like to setup the Slack application manually you can do so following Setup Slack Application guide below.

Configuring rails-approvals

Rails::Approvals needs three things to work:

1. The Slack Bot User OAuth Token generated after installing the Slack application to your workspace. This lets the gem publish messages to your configured Slack channel.
2. The Webhook signing secret generated by Slack.
3. The Slack channel you'd like to send approval requests to.

Each of these can be configured by environment variables or manually in your environment file. We strongly do not recommend checking in any API tokens into version control and using environment variables to configure them.

Rails.application.configure do
  # Enabled by default in production. If you'd like to enable approvals in
  # staging or other environments you can do so here.
  config.rails.approvals.enabled = true

  # Can be configured with RAILS_APPROVALS_SLACK_CHANNEL by default, or provided
  # explicitely.
  config.rails.approvals.slack.channel = "#rails-approvals"

  # Can be configured with RAILS_APPROVALS_SLACK_TOKEN. Strongly do not
  # recommended checking this into version control.
  config.rails.approvals.slack.token = ENV['RAILS_APPROVALS_SLACK_TOKEN']

  # Can be configured with RAILS_APPROVALS_SLACK_SIGNING_SECRET. Strongly do not
  # recommended checking this into version control.
  config.rails.approvals.slack.signing_secret = ENV['RAILS_APPROVALS_SLACK_SIGNING_SECRET']
end

There are additional settings you can configure should you like, such as:

• How long approval requests are valid for (defaults to 10 minutes)
• If the user is prompted to identify who they are (defaults to $USER)
• If a reason is required.

Mounting the Rails::Approvals engine

When you respond to approval requests within Slack, Slack will deliver a webhook message to your configured application to permit or deny access accordingly. Rails::Approvals includes a built in controller to verify the message from Slack using the required signing secret, lookup the approval request, and handle the approved/denied response.

You will want to mount the Rails::Approvals::Engine within your config/routes.rb file:

Rails.application.routes.draw do
  mount Rails::Approvals::Engine => "/rails/approvals"

  # existing routes here
end

For Slack to know where to send approval request responses you must provide a webhook URL. Using the URL below, replace example.com with your application's domain and enter it within the Interactivity & Shortcuts section of your Slack application settings:

https://example.com/rails/approvals/slack/webhook

Run the database migration

Rails::Approvals uses an ActiveRecord model to keep track of all pending approval requests, who requested them, the reason provided and more. Install and run the required database migration below:

bin/rails railsapprovals:install:migrations
bin/rails db:migrate

You are welcome to check out the migration before running it.

Deploy

Now that you've installed rails-approvals, setup your Slack application & installed it to your workspace, you're ready to go!

How does Rails::Approvals work?

Rails::Approvals works by adding a blocking approval request before a Rails console can be started.

module Rails
  module Approvals
    class Railtie < ::Rails::Railtie
      console do
        Rails::Approvals.start!
      end
    end
  end
end

An Rails::Approvals::Request record is created which publishes the approval request to Slack and waits for someone to respond.

When an approval request is ✅ approved, the console session will continue as normal. When an approval response is 🛑 denied or ⚠️ times out, the process will exit immediately.

Setup Slack Application

If you'd like to create your Slack application manually, you can do so by following the instructions below:

1. Create a new Slack application for your desired Slack workspace.
2. Next, under Features, select OAuth & Permissions.
3. Add the chat:write scope under Bot Token Scopes. This is the only permission you need.
4. Now that you've added the required permission for Rails::Approvals to work, you must install the new application in your Slack workspace.
5. Under Settings, select Install App.
6. Install your Slack application to your workspace by following the prompt after clicking Install to Workspace.
7. Copy the Bot User OAuth Token and configure a RAILS_APPROVALS_SLACK_TOKEN environment variable for your application.
8. Next, under Features, select Interactivity & Shortcuts.
9. Enable Interactivity and provide the Request URL per the webhook URL instructions above.
10. Next, under Settings, select Basic Information.
11. Copy the Signing Secret under App Credentials and configure your RAILS_APPROVALS_SLACK_SIGNING_SECRET environment variable.

Contributing

1. Fork it ( https://github.com/cased/rails-approvals/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.