Join us for office hours !

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. Glitch
    2. Heroku
    3. ZEIT Now
  3. Share the app
  4. Combining apps
  5. Error tracking
  6. Serverless Deployments

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.
  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 an 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.

Glitch

Glitch lets you host node applications for free and edit them directly in your browser. It’s great for experimentation and entirely sufficient for simple apps.

  1. Create a new app on Glitch.
  2. Click on your app name on the top-right, press on advanced options and then on Import from GitHub (You will need to login with your GitHub account to enable that option). Enter the full repository name you want to import, e.g. for the welcome app it would be behaviorbot/new-issue-welcome. The new-issue-welcome app is a great template to get started with your own app, too!
  3. Next open the .env file and replace its content with
    APP_ID=<your app id>
    WEBHOOK_SECRET=<your app secret>
    PRIVATE_KEY_PATH=.data/private-key.pem
    NODE_ENV=production
    
    Replace the two <...> placeholders with the values from your app. The .env file cannot be accessed or seen by others.
  4. Press the New File button and enter .data/private-key.pem. Paste the content of your GitHub App’s private-key.pem in there and save it. Files in the .data folder cannot be seen or accessed by others, so your private key is safe.
  5. That’s it, your app should have already started :thumbsup: Press on the Show button on top and paste the URL as the value of Webhook URL. Ensure that you remove /probot from the end of the Webhook URL that was just pasted.

Enjoy!

Bonus: You can deploy your app using glitch-deploy directly from your terminal or as continuous deployment.

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
    

ZEIT Now

Deploy Probot as a Serverless Function to ZEIT Now. After creating the GitHub App:

  1. Install Now CLI with npm i -g now and login with now login

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

  3. Install probot-serverless-now

     $ npm install probot-serverless-now
    
  4. Update package.json and add build script to generate your HTML landing page, for example:

    {
      "scripts": {
        "build": "mkdir public && echo 'Hello World' > public/index.html"
      }
    }
    
  5. Create a new file /api/index.js with the following:

    const { toLambda } = require('probot-serverless-now');
    const app = require('./path/to/your/app.js');
    module.exports = toLambda(app);
    
  6. Create a new file now.json with the following:

    {
      "env": {
        "APP_ID":"@probot-api-id",
        "WEBHOOK_SECRET": "@probot-webhook-secret",
        "PRIVATE_KEY": "@probot-private-key"
      }
    }
    

    NOTE: Add LOG_LEVEL=trace to get verbose logging, or add LOG_LEVEL=info instead to show less details.

  7. Run now secrets add probot-api-id aaa, now secrets add probot-webhook-secret bbb, now secrets add probot-private-key "$(cat ~/Downloads/*.private-key.pem | base64)" replacing the aaa and bbb with the values for those variables.

  8. Deploy with now or connect your GitHub repository](https://zeit.co/github) to ZEIT Now and deploy on git push.

  9. 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).

  10. You can optionally add a Custom Domain and deploy to production with the following:

     $ now --prod
    
  11. Visit https://your-deployment.now.sh/api to invoke the serverless function.

Share the app

The Probot website includes a list of featured apps. Consider adding your app to the website so others can discover and use it.

Combining apps

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

{
  "name": "my-probot-app",
  "private": true,
  "dependencies": {
    "probot-autoresponder": "probot/autoresponder",
    "probot-settings": "probot/settings"
  },
  "scripts": {
    "start": "probot run"
 },
 "probot": {
   "apps": [
     "probot-autoresponder",
     "probot-settings"
   ]
 }
}

Error tracking

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

  1. Install Sentry from Marketplace (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.

Serverless

Serverless abstracts away the most menial parts of building an application, leaving developers to write code and not actively manage scaling for their applications. The Serverless Deployment section will show you how to deploy you application using functions instead of servers.

Found a mistake or want to help improve this documentation? Suggest changes on GitHub

Get occasional updates on new apps & features.

Star

with by the Probot community

Code licensed ISC Docs licensed CC-BY-4.0