Skip to content

deployment.md

Latest commit

 

History

History
325 lines (223 loc) · 11.3 KB

deployment.md

File metadata and controls

325 lines (223 loc) · 11.3 KB
next http
title Deployment

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:

Register the GitHub App

Every deployment will need a GitHub App registration.

  1. Register 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 (e.g. with openssl rand -base64 32) and save it because you'll need it in a minute to configure your Probot 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.

As node app

Probot can run your app function using the probot binary. If your app function lives in ./app.js, you can start it as node process using probot run ./app.js

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/api/github/webhooks.

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

Render

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

  1. Sign up at Render and access your dashboard.

  2. Click "New Web Service" and select your GitHub repository.

  3. Set the "Build Command" and "Start Command". For a typical Probot app, use:

    Build Command: npm install
Start Command: npm start

  4. Set the Instance Type to "Free" or any other type you prefer.

  5. Set environment variables:

    APP_ID=aaa
WEBHOOK_SECRET=bbb
PRIVATE_KEY=<paste your private key here>
PORT=3000
    • Be sure to add PORT=3000 because Render's default port is 10000, but Probot expects 3000.
    • For PRIVATE_KEY, paste the contents of your private key directly.

  6. Deploy the app by clicking the Deploy Web Service button. Render will automatically build and start your service.

  7. Go back to your app settings page and update the Webhook URL to the URL of your Render deployment, including the default webhook path, e.g. https://your-app.onrender.com/api/github/webhooks.

  8. Your app should be up and running! To verify that your app is receiving webhook data, check the "Logs" tab in the Render dashboard.

As serverless function

When deploying your Probot app to a serverless/function environment, you don't need to worry about handling the http webhook requests coming from GitHub, the platform takes care of that. In many cases you can use createNodeMiddleware directly, e.g. for Vercel or Google Cloud Function.

import { Probot, createProbot } from "probot";
import { createMyMiddleware } from "my-probot-middleware";
import myApp from "./my-app.js";

export default createMyMiddleware(myApp, { probot: createProbot() });

For other environments such as AWS Lambda, Netlify Functions or GitHub Actions, you can use one of Probot's adapters.

AWS Lambda

// handler.js
import {
  createLambdaFunction,
  createProbot,
} from "@probot/adapter-aws-lambda-serverless";
import appFn from "./app.js";

export const webhooks = createLambdaFunction(appFn, {
  probot: createProbot(),
});

Learn more

Examples

Please add yours!

Azure Functions

// ProbotFunction/index.js
import {
  createProbot,
  createAzureFunction,
} from "@probot/adapter-azure-functions";
import app from "../app.js";

export default createAzureFunction(app, { probot: createProbot() });

Learn more

Examples

Please add yours!

Google Cloud Functions

// function.js
import { createNodeMiddleware, createProbot } from "probot";
import app from "./app.js";

const middleware = await createNodeMiddleware(app, {
  probot: createProbot(),
  webhooksPath: "/",
});
exports.probotApp = (req, res) => {
  middleware(req, res, () => {
    res.writeHead(404);
    res.end();
  });
};

Examples

Please add yours!

GitHub Actions

import { run } from "@probot/adapter-github-actions";
import app from "./app.js";

run(app);

Learn more

Examples

Please add yours!

Vercel

// api/github/webhooks/index.js
import { createNodeMiddleware, createProbot } from "probot";

import app from "../../../app.js";

export default await createNodeMiddleware(app, {
  probot: createProbot(),
  webhooksPath: "/api/github/webhooks",
});

Important: Set NODEJS_HELPERS environment variable to 0 in order to prevent Vercel from parsing the response body. See Disable Helpers for detail.

Examples

Please add yours!

Netlify Functions

Netlify Functions are deployed on AWS by Netlify itself. So we can use @probot/adapter-aws-lambda-serverless adapter for Netlify Functions as well.

// functions/index.js
import {
  createLambdaFunction,
  createProbot,
} from "@probot/adapter-aws-lambda-serverless";
import appFn from "../src/app";

export const handler = createLambdaFunction(appFn, {
  probot: createProbot(),
});

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"]
  }
}

Note that this feature is only supported when run as Node app. For serverless/function deployments, create a new Probot app that combines others programmatically

// app.js
import autoresponder from "probot-autoresponder";
import settings from "probot-settings";

export default async (app, options) => {
  await autoresponder(app, options);
  await settings(app, options);
};

Error tracking

Probot logs messages using pino. There is a growing number of tools that consume these logs and send them to error tracking services: https://getpino.io/#/docs/transports.

By default, Probot can send errors to Sentry using its own transport @probot/pino. Set the SENTRY_DSN environment variable to enable it.