Rails-approvals
rails-approvals is a gem which makes it very easy to add approval workflows via Slack to control who can start Rails console sessions or run database migrations in production.
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.
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.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
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.
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
- 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.
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
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
Now that you've installed
rails-approvals, setup your Slack application & installed it to your workspace, you're ready to go!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.
If you'd like to create your Slack application manually, you can do so by following the instructions below:
- 1.
- 2.Next, under Features, select OAuth & Permissions.
- 3.Add the
chat:writescope 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_TOKENenvironment 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_SECRETenvironment variable.
- 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
Last modified 1yr ago