To develop a Probot app, you will first need a recent version of Node.js installed. Open a terminal and run node -v
to verify that it is installed and is at least 8.3.0 or later. Otherwise, install the latest version.
create-probot-app is the best way to start building a new app. It will generate a new app with everything you need to get started and run your app in production.
To get started, run one of these commands:
$ npx create-probot-app my-first-app
$ yarn create probot-app my-first-app
create-probot-app
accepts an optionaltemplate
argument which accepts the following values:basic-js
,checks-js
,git-data-js
,deploy-js
andbasic-ts
(use this one for TypeScript support).
This will ask you a series of questions about your app, which should look something like this:
Let's create a Probot app!
? App name: my-first-app
? Description of app: A 'Hello World' GitHub App built with Probot
? Author's full name: Katie Horne
? Author's email address: katie@auth0.com
? Homepage:
? GitHub user or org name: khorne3
? Repository name: my-first-app
? Which template would you like to use? (Use arrow keys)
❯ basic-js
checks-js
git-data-js
deploy-js
basic-ts
created files...
Finished scaffolding files!
Installing Node dependencies!
Done! Enjoy building your Probot app!
The most important files here are index.js
, which is where the code for your app will go, and package.json
, which makes this a standard npm module.
Now you're ready to run the app on your local machine. Run npm run dev
to start the server:
Note: If you're building a TypeScript app, be sure to run
npm run build
first!
> testerino@1.0.0 dev /Users/hiimbex/Desktop/testerino
> nodemon
[nodemon] 1.18.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching: .env *.*
[nodemon] starting `npm start`
> testerino@1.0.0 start /Users/hiimbex/Desktop/testerino
> probot run ./index.js
01:57:22.365Z INFO probot:
Welcome to Probot! Go to http://localhost:3000 to get started.
01:57:22.428Z INFO probot: Forwarding https://smee.io/1S10MsoRSjZKWKMt to http://localhost:3000/
01:57:22.431Z INFO probot: Listening on http://localhost:3000
01:57:22.564Z INFO probot: Connected https://smee.io/1S10MsoRSjZKWKMt
The dev
script will start your app using nodemon, which will watch for any files changes in your local development environment and automatically restart the server.
To automatically configure your GitHub App, follow these steps:
npm run dev
..env
and notice it will be populated with values GitHub sends us in the course of that redirect.GitHub App Manifests--otherwise known as easy app creation--make it simple to generate all the settings necessary for a GitHub App. This process abstracts the Configuring a GitHub App section. You can learn more about how GitHub App Manifests work and how to change your settings for one via the GitHub Developer Docs.
If you created an App with a manifest, you can skip this section; your app is already configured! If you ever need to edit those settings, you can visit
https://github.com/settings/apps/your-app-name
To run your app in development, you will need to configure a GitHub App to deliver webhooks to your local machine.
.env.example
to .env
in the same directory.WEBHOOK_PROXY_URL
in .env
to the URL that you are redirected to.WEBHOOK_PROXY_URL
from the previous step.development
(Note: For optimal security, Probot apps require this secret be set, even though it's optional on GitHub.)..env
and set APP_ID
to the ID of the app you just created. The App ID can be found in your app settings page here You'll need to create a test repository and install your app by clicking the "Install" button on the settings page of your app, e.g. https://github.com/apps/your-app
Other available scripts
$ npm start
to start your app without watching files.$ npm run lint
to lint your code using standard.$ npm install
and restart the server if package.json
has changed.$ LOG_LEVEL=trace npm start
If you take a look to the npm start
script, this is what it runs: probot run ./index.js
. This is nice, but you sometimes need more control over how your Node.js application is executed. For example, if you want to use custom V8 flags, ts-node
, etc. you need more flexibility. In those cases there's a simple way of executing your probot application programmatically:
// main.js
const { Probot } = require('probot')
const app = require('./index.js')
// pass a probot app as a function
Probot.run(app)
Now you can run main.js
however you want.
Found a mistake or want to help improve this documentation? Suggest changes on GitHub