next | title |
---|---|
http |
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:
Every deployment will need a GitHub App registration.
-
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.
-
Download the private key from the app.
-
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.
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
.
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
Glitch lets you host node applications for free and edit them directly in your browser. It鈥檚 great for experimentation and entirely sufficient for simple apps.
- Create a new app on Glitch.
- 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 bebehaviorbot/new-issue-welcome
. Thenew-issue-welcome
app is a great template to get started with your own app, too! - Next open the
.env
file and replace its content withReplace the twoAPP_ID=<your app id> WEBHOOK_SECRET=<your app secret> PRIVATE_KEY_PATH=.data/private-key.pem NODE_ENV=production
<...>
placeholders with the values from your app. The.env
file cannot be accessed or seen by others. - Press the
New File
button and enter.data/private-key.pem
. Paste the content of your GitHub App鈥檚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. - That鈥檚 it, your app should have already started 馃憤 Press on the
Show
button on top and paste the URL as the value ofWebhook URL
. Ensure that you remove/probot
from the end of theWebhook URL
that was just pasted.
Enjoy!
Probot runs like any other Node app on Heroku. After creating the GitHub App:
-
Make sure you have the Heroku CLI client installed.
-
Clone the app that you want to deploy. e.g.
git clone https://github.com/probot/stale
-
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
-
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/
. -
Configure the Heroku app, replacing the
APP_ID
andWEBHOOK_SECRET
with the values for those variables, and setting the path for thePRIVATE_KEY
:$ heroku config:set APP_ID=aaa \ WEBHOOK_SECRET=bbb \ PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
-
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
-
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
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.
// 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
- Probot's official adapter for AWS Lambda using the Serverless framework: @probot/adapter-aws-lambda-serverless
Examples
- Probot's "Hello, world!" example deployed to AWS Lambda: probot/example-aws-lambda-serverless
- Issue labeler bot deployed to AWS Lambda: riyadhalnur/issuelabeler
- Auto-Me-Bot is deployed to AWS Lambda without using the serverless framework and adapter: TomerFi/auto-me-bot
Please add yours!
// ProbotFunction/index.js
import {
createProbot,
createAzureFunction,
} from "@probot/adapter-azure-functions";
import app from "../app.js";
export default createAzureFunction(app, { probot: createProbot() });
Learn more
- Probot's official adapter for Azure functions: @probot/adapter-azure-functions
Examples
- Probot's "Hello, world!" example deployed to Azure functions: probot/example-azure-function
Please add yours!
// function.js
import { createNodeMiddleware, createProbot } from "probot";
import app from "./app.js";
exports.probotApp = createNodeMiddleware(app, { probot: createProbot() });
Examples
- Probot's "Hello, world!" example deployed to Google Cloud Functions: probot/example-google-cloud-function
Please add yours!
import { run } from "@probot/adapter-github-actions";
import app from "./app.js";
run(app);
Learn more
- Probot's official adapter for GitHub Actions: @probot/adapter-github-actions
Examples
- Probot's "Hello, world!" example deployed as a GitHub Action: probot/example-github-action
Please add yours!
Begin is a service to deploy serverless applications build using the Architect to AWS.
-
Add the
@http
pragma to yourapp.arc
file@app my-app-name @http post /api/github/webhooks
-
Make sure to configure your app using environment variables
-
Create the
src/http/post-api-github-webhooks
folder with the following files{ "name": "http-post-api-github-webhooks", "dependencies": {} }
in the new directory, install the
probot
and@architect/functions
cd src/http/post-api-github-webhooks npm install probot @architect/functions
-
Create
src/http/post-api-github-webhooks/app.js
with your Probot application function, e.g./** * @param {import('probot').Probot} app */ export default (app) => { app.log("Yay! The app was loaded!"); app.on("issues.opened", async (context) => { return context.octokit.issues.createComment( context.issue({ body: "Hello, World!" }) ); }); };
-
Create
src/http/post-api-github-webhooks/index.js
with the request handler. See /probot/example-begin/src/http/post-api-github-webhooks/index.js for an example.
Examples
Please add yours!
// api/github/webhooks/index.js
import { createNodeMiddleware, createProbot } from "probot";
import app from "../../../app.js";
export default 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 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(),
});
The Probot website includes a list of featured apps. Consider adding your app to the website so others can discover and use it.
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);
};
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.