probot/docs/deployment.md

next

next
docs/best-practices.md

Deployment

Every app can either be deployed stand-alone, or combined with other apps in one deployment.

Heads up! Note that most apps in the @probot organization have an official hosted app that you can use for your open source project. Use the hosted instance if you don't want to deploy your own.

Contents:

1. Create the GitHub App
2. Deploy the app
   1. Heroku
   2. Now
3. Combining apps

Create the GitHub App

Every deployment will need an App.

1. Create a new GitHub App with:

   • Homepage URL: the URL to the GitHub repository for your app
   • Webhook URL: Use https://example.com/ for now, we'll come back in a minute to update this with the URL of your deployed app.
   • Webhook Secret: Generate a unique secret with openssl rand -base64 32 and save it because you'll need it in a minute to configure your deployed app.
   • Permissions & events: See docs/deploy.md in the app for a list of the permissions and events that it needs access to.

2. Download the private key from the app.

3. Make sure that you click the green Install button on the top left of the app page. This gives you an option of installing the app on all or a subset of your repositories.

Deploy the app

To deploy a app to any cloud provider, you will need 3 environment variables:

• APP_ID: the ID of the app, which you can get from the app settings page.
• WEBHOOK_SECRET: the Webhook Secret that you generated when you created the app.

And one of:

• PRIVATE_KEY: the contents of the private key you downloaded after creating the app, OR...
• PRIVATE_KEY_PATH: the path to a private key file.

PRIVATE_KEY takes precedence over PRIVATE_KEY_PATH.

Heroku

Probot runs like any other Node app on Heroku. After creating the GitHub App:

1. Make sure you have the Heroku CLI client installed.

2. Clone the app that you want to deploy. e.g. git clone https://github.com/probot/stale

3. Create the Heroku app with the heroku create command:

    $ heroku create
    Creating arcane-lowlands-8408... done, stack is cedar
    http://arcane-lowlands-8408.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git
    Git remote heroku added
   

4. Go back to your app settings page and update the Webhook URL to the URL of your deployment, e.g. http://arcane-lowlands-8408.herokuapp.com/.

5. Configure the Heroku app, replacing the APP_ID and WEBHOOK_SECRET with the values for those variables, and setting the path for the PRIVATE_KEY:

    $ heroku config:set APP_ID=aaa \
        WEBHOOK_SECRET=bbb \
        PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
   

6. Deploy the app to heroku with git push:

    $ git push heroku master
    ...
    -----> Node.js app detected
    ...
    -----> Launching... done
          http://arcane-lowlands-8408.herokuapp.com deployed to Heroku
   

7. Your app should be up and running! To verify that your app is receiving webhook data, you can tail your app's logs:

    $ heroku config:set LOG_LEVEL=trace
    $ heroku logs --tail
   

Now

Zeit Now is a great service for running Probot apps. After creating the GitHub App:

1. Install the now CLI with npm i -g now

2. Clone the app that you want to deploy. e.g. git clone https://github.com/probot/stale

3. Run now to deploy, replacing the APP_ID and WEBHOOK_SECRET with the values for those variables, and setting the path for the PRIVATE_KEY:

    $ now -e APP_ID=aaa \
        -e WEBHOOK_SECRET=bbb \
        -e PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
   

4. Once the deploy is started, go back to your app settings page and update the Webhook URL to the URL of your deployment (which now has kindly copied to your clipboard).

Your app should be up and running!

Combining apps

To deploy a bot that includes multiple apps, create a new app that has the apps listed as dependencies in package.json:

{
  "name": "my-probot",
  "private": true,
  "dependencies": {
    "probot-autoresponder": "probot/autoresponder",
    "probot-configurer": "probot/configurer"
  },
  "scripts": {
    "start": "probot run"
 },
 "probot": {
   "plugins": [
     "probot-autoresponder",
     "probot-configurer"
   ]
 }
}

Error tracking

Probot comes bundled with a client for the Sentry exception tracking platform. To enable Sentry:

1. Create a Sentry.io Account (with 10k events/month free) or host your own instance (Students can get extra Sentry credit)
2. Follow the setup instructions to find your DSN.
3. Set the SENTRY_DSN environment variable with the DSN you retrieved.