Skip to content

Latest commit

 

History

History
113 lines (82 loc) · 5.52 KB

README.md

File metadata and controls

113 lines (82 loc) · 5.52 KB
Raw

hubot-heroku

npm version CircleCI Status

A hubot library that exposes heroku commands via Heroku's Platform API, with focus of letting non privileged developers carry out tasks around deployments, but not run dangerous commands or get access to the data.

Background

Under Heroku's permission model, giving someone access to push/promote to production means giving full access to the data as well. This is generally not a good practice and for certain companies, it might be non-compliant.

Our team wanted to let every engineer do deployments without giving production access. We started this by using atmos/hubot-deploy and atmos/heaven, but that didn't the ability to run migrations, set config variables etc. hubot-heroku was made with this consideration in mind.

Considerations

  • It's an opionated helper to get things done on Heroku, not an API client
  • Only use Heroku's Platform API, no direct running of commands in Bash
  • Test coverage for commands, especially if we're implementing
  • Certain commands (such as migrate) only work for Rails now =(
  • Actual deployment is not the focus of this robot

By the way, I'm also actively looking for co-contributors!

What about actual deployments?

Deployment usually involves some form of CI process. Hence it is best suited for a robust solution like Github deployments, where you can set required CI contexts etc.

This robot is focused on letting you run auxiliary commands around the heroku system, so developers don't have to be given production access to independently manage deployments.

Auth

You can restrict command usage to specific roles using the hubot-auth package. Role names take the form heroku-<app>.

To enable auth:

  1. npm install hubot-auth --save
  2. Add hubot-auth to external-scripts.json (e.g. ["hubot-auth", "some-other-plugin"])
  3. Set HUBOT_HEROKU_USE_AUTH to true.
  4. Assign roles: hubot <user> has heroku-<app> role

Security

You can set config variables using this. Hence the Heroku API key used should not have access to your hubot instance on Heroku. For example:

hubot heroku config:set my-hubot HUBOT_ADMIN=dr_evil
# Muhaha, now I'm to use hubot's other commands to take over the world

You can also avoid this if you are using auth as described above, in which case you can ensure only admins have the role necessary to set config variables on the hubot instance.

Installation

  1. npm install hubot-heroku --save
  2. Add hubot-heroku to external-scripts.json (e.g. ["hubot-heroku", "some-other-plugin"])
  3. Before deployment, set HUBOT_HEROKU_API_KEY to a heroku account's API key. This user must have access to the apps you want to use this script on.
  4. The full list of commands can be obtained using hubot help. The commands usually follow hubot heroku

The API key can be obtained here.

Heroku API Key Illustration

Usage

Use hubot help to look for the commands. They are all prefixed by heroku. (e.g. hubot heroku restart my-app) Some commands (hubot help will be a better source of truth):

  • hubot heroku list apps <app name filter> - Lists all apps or filtered by the name
  • hubot heroku info <app> - Returns useful information about the app
  • hubot heroku dynos <app> - Lists all dynos and their status
  • hubot heroku releases <app> - Latest 10 releases
  • hubot heroku rollback <app> - Rollback to a release
  • hubot heroku restart <app> <dyno> - Restarts the specified app or dyno/s (e.g. worker or web.2)
  • hubot heroku migrate <app> - Runs migrations. Remember to restart the app =)
  • hubot heroku config <app> - Get config keys for the app. Values not given for security
  • hubot heroku config:set <app> <KEY=value> - Set KEY to value. Case sensitive and overrides present key
  • hubot heroku config:unset <app> <KEY> - Unsets KEY, does not throw error if key is not present
  • hubot heroku ps:scale <app> <type>=<size>(:<quantity>) - Scales dyno quantity up or down

For example, hubot heroku config:set API_KEY=12345

Troubleshooting

If you get hubot errors, this might help:

  • 400 - Bad request. Hit me with an issue
  • 401 - Most likely the API key is incorrect or missing
  • 402 - According to Heroku, you need to pay them
  • 403 - You don't have access to that app. Perhaps it's a typo on the app name?
  • 404 - No such API. Hit me with an issue.
  • 405+ - Hit me with an issue

Reference the API documentation for more information. Search for "Error Responses".

Tests

  • Mocha
  • Chai for BDD expect syntax

Run tests by running npm test

Debugging

Get Node Inspector working

npm install -g node-inspector
node-inspector --no-preload --web-port 8123

Get hubot to run with debugging on

# In your hubot folder
npm link /path/to/hubot-heroku
coffee --nodejs --debug node_modules/.bin/hubot

Visit http://127.0.0.1:8123/debug?port=5858 and use debugger statements to pause execution.

Contributing

PRs and Issues greatly welcomed. Please read Contributing for more information.