_(Example: `1234`)_
| -| `PRIVATE_KEY` or `PRIVATE_KEY_PATH` | `new Probot({ privateKey })` | The contents of the private key for your GitHub App. If you're unable to use multiline environment variables, use base64 encoding to convert the key to a single line string. See the [Deployment](deployment.md) docs for provider specific usage. When using the `PRIVATE_KEY_PATH` environment variable, set it to the path of the `.pem` file that you downloaded from your GitHub App registration._(Example: `path/to/key.pem`)_
| -| **Webhook options** | | -| `WEBHOOK_PROXY_URL` | `new Server({ webhookProxy })` | Allows your local development environment to receive GitHub webhook events. Go to https://smee.io/new to get started._(Example: `https://smee.io/your-custom-url`)_
| -| `WEBHOOK_SECRET` | `new Probot({ secret })` | The webhook secret used when creating a GitHub App. 'development' is used as a default, but the value in `.env` needs to match the value configured in your App settings on GitHub. Note: GitHub marks this value as optional, but for optimal security it's required for Probot apps. **Required**_(Example: `development`)_
| +| Environment Variable | [Programmatic Argument](/docs/development.md#run-probot-programmatically) | Description | +| ----------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `APP_ID` | `new Probot({ appId })` | The App ID assigned to your GitHub App. **Required**_(Example: `1234`)_
| +| `PRIVATE_KEY` or `PRIVATE_KEY_PATH` | `new Probot({ privateKey })` | The contents of the private key for your GitHub App. If you're unable to use multiline environment variables, use base64 encoding to convert the key to a single line string. See the [Deployment](deployment.md) docs for provider specific usage. When using the `PRIVATE_KEY_PATH` environment variable, set it to the path of the `.pem` file that you downloaded from your GitHub App registration._(Example: `path/to/key.pem`)_
| +| **Webhook options** | | +| `WEBHOOK_PROXY_URL` | `new Server({ webhookProxy })` | Allows your local development environment to receive GitHub webhook events. Go to https://smee.io/new to get started._(Example: `https://smee.io/your-custom-url`)_
| +| `WEBHOOK_SECRET` | `new Probot({ secret })` | The webhook secret used when creating a GitHub App. 'development' is used as a default, but the value in `.env` needs to match the value configured in your App settings on GitHub. Note: GitHub marks this value as optional, but for optimal security it's required for Probot apps. **Required**_(Example: `development`)_
| -For more on the set up of these items, check out [Configuring a GitHub App](./development.md#configuring-a-github-app). +For more on the set up of these items, check out [Configuring a GitHub App](/docs/development.md#configuring-a-github-app). Some less common environment variables are: -| Environment Variable | [Programmatic Argument](./development.md#run-probot-programmatically) | Description | -| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GHE_HOST` | `new Probot({ Octokit: ProbotOctokit.defaults({ baseUrl }) })` | The hostname of your GitHub Enterprise instance._(Example: `github.mycompany.com`)_
| -| `GHE_PROTOCOL` | `new Probot({ Octokit: ProbotOctokit.defaults({ baseUrl }) })` | The protocol of your GitHub Enterprise instance. Defaults to HTTPS. Do not change unless you are certain._(Example: `https`)_
| -| `GH_ORG` | - | The organization where you want to register the app in the app creation manifest flow. If set, the app is registered for an organization (https://github.com/organizations/ORGANIZATION/settings/apps/new), if not set, the GitHub app would be registered for the user account (https://github.com/settings/apps/new). | -| `LOG_FORMAT` | - | By default, logs are formatted for readability in development. You can set this to `json` in order to disable the formatting | -| `LOG_LEVEL` | `const log = require('pino')({ level })` | The verbosity of logs to show when running your app, which can be `fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`. Default: `info` | -| `LOG_LEVEL_IN_STRING` | - | By default, when using the `json` format, the level printed in the log records is an int (`10`, `20`, ..). This option tells the logger to print level as a string: `{"level": "info"}`. Default `false` | -| `LOG_MESSAGE_KEY` | `const log = require('pino')({ messageKey: 'msg' })` | Only relevant when `LOG_FORMAT` is set to `json`. Sets the json key for the log message. Default: `msg` | -| `SENTRY_DSN` | - | Set to a [Sentry](https://sentry.io/) DSN to report all errors thrown by your app._(Example: `https://1234abcd@sentry.io/12345`)_
| -| `PORT` | `new Server({ port })` | The port to start the local server on. Default: `3000` | -| `HOST` | `new Server({ host })` | The host to start the local server on. | -| `WEBHOOK_PATH` | `new Server({ webhookPath })` | The URL path which will receive webhooks. Default: `/` | -| `REDIS_URL` | `new Probot({ redisConfig })` | Set to a `redis://` url as connection option for [ioredis](https://github.com/luin/ioredis#connect-to-redis) in order to enable [cluster support for request throttling](https://github.com/octokit/plugin-throttling.js#clustering)._(Example: `redis://:secret@redis-123.redislabs.com:12345/0`)_
| +| Environment Variable | [Programmatic Argument](/docs/development.md#run-probot-programmatically) | Description | +| --------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GHE_HOST` | `new Probot({ Octokit: ProbotOctokit.defaults({ baseUrl }) })` | The hostname of your GitHub Enterprise instance._(Example: `github.mycompany.com`)_
| +| `GHE_PROTOCOL` | `new Probot({ Octokit: ProbotOctokit.defaults({ baseUrl }) })` | The protocol of your GitHub Enterprise instance. Defaults to HTTPS. Do not change unless you are certain._(Example: `https`)_
| +| `GH_ORG` | - | The organization where you want to register the app in the app creation manifest flow. If set, the app is registered for an organization (https://github.com/organizations/ORGANIZATION/settings/apps/new), if not set, the GitHub app would be registered for the user account (https://github.com/settings/apps/new). | +| `LOG_FORMAT` | - | By default, logs are formatted for readability in development. You can set this to `json` in order to disable the formatting | +| `LOG_LEVEL` | `const log = require('pino')({ level })` | The verbosity of logs to show when running your app, which can be `fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`. Default: `info` | +| `LOG_LEVEL_IN_STRING` | - | By default, when using the `json` format, the level printed in the log records is an int (`10`, `20`, ..). This option tells the logger to print level as a string: `{"level": "info"}`. Default `false` | +| `LOG_MESSAGE_KEY` | `const log = require('pino')({ messageKey: 'msg' })` | Only relevant when `LOG_FORMAT` is set to `json`. Sets the json key for the log message. Default: `msg` | +| `SENTRY_DSN` | - | Set to a [Sentry](https://sentry.io/) DSN to report all errors thrown by your app._(Example: `https://1234abcd@sentry.io/12345`)_
| +| `PORT` | `new Server({ port })` | The port to start the local server on. Default: `3000` | +| `HOST` | `new Server({ host })` | The host to start the local server on. | +| `WEBHOOK_PATH` | `new Server({ webhookPath })` | The URL path which will receive webhooks. Default: `/` | +| `REDIS_URL` | `new Probot({ redisConfig })` | Set to a `redis://` url as connection option for [ioredis](https://github.com/luin/ioredis#connect-to-redis) in order to enable [cluster support for request throttling](https://github.com/octokit/plugin-throttling.js#clustering)._(Example: `redis://:secret@redis-123.redislabs.com:12345/0`)_
| For more information on the formatting conventions and rules of `.env` files, check out [the npm `dotenv` module's documentation](https://www.npmjs.com/package/dotenv#rules). diff --git a/docs/deployment.md b/docs/deployment.md index 29a1b77f15..2d8e1ba951 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -123,7 +123,7 @@ Probot runs like [any other Node app](https://devcenter.heroku.com/articles/depl ### 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`](./development.md#use-createNodeMiddleware) directly, e.g. for Vercel or Google Cloud 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`](/docs/development.md#use-createNodeMiddleware) directly, e.g. for Vercel or Google Cloud Function. ```js const { Probot, createProbot } = require("probot"); diff --git a/docs/development.md b/docs/development.md index 55127f7f7e..43c617ba4c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -173,7 +173,7 @@ Now you can run `main.js` however you want. The [`run`](https://github.com/probot/probot/blob/master/src/run.ts) function that gets executed when running `probot run ./index.js` does two main things 1. Read configuration from environment variables and local files -2. Start a [`Server`](https://probot.github.io/api/latest/classes/server.html) instance +2. Start a [`Server`](https://probot.github.io/api/latest/classes/server_server.Server.html) instance Among other things, using the Server instance permits you to set your own [`Octokit` constructor](https://github.com/octokit/core.js) with custom plugins and a custom logger. @@ -196,7 +196,7 @@ async function startServer() { } ``` -The `server` instance gives you access to the express app instance (`server.expressApp`) as well as the [`Probot`](https://probot.github.io/api/latest/classes/probot.html) instance (`server.probotApp`). +The `server` instance gives you access to the express app instance (`server.expressApp`) as well as the [`Probot`](https://probot.github.io/api/latest/classes/probot.Probot.html) instance (`server.probotApp`). ### Use createNodeMiddleware @@ -235,7 +235,7 @@ module.exports = createNodeMiddleware(app, { ### Use probot -If you don't use Probot's http handling in order to receive and verify events from GitHub via webhook requests, you can use the [`Probot`](https://probot.github.io/api/latest/classes/probot.html) class directly. +If you don't use Probot's http handling in order to receive and verify events from GitHub via webhook requests, you can use the [`Probot`](https://probot.github.io/api/latest/classes/probot.Probot.html) class directly. ```js const { Probot } = require("probot"); @@ -259,7 +259,7 @@ async function example() { } ``` -Using the `Probot` class directly is great for [writing tests](./testing.md) for your Probot app function. It permits you to pass a custom logger to test for log output, disable throttling, request retries, and much more. +Using the `Probot` class directly is great for [writing tests](/docs/testing.md) for your Probot app function. It permits you to pass a custom logger to test for log output, disable throttling, request retries, and much more. ### Use Probot's Octokit diff --git a/docs/github-api.md b/docs/github-api.md index f557bc7c65..cc5e65d743 100644 --- a/docs/github-api.md +++ b/docs/github-api.md @@ -86,7 +86,7 @@ Check out the [GitHub GraphQL API docs](https://docs.github.com/en/graphql) to l ## Unauthenticated Events -When [receiving webhook events](./webhooks.md), `context.octokit` is _usually_ an authenticated client, but there are a few events that are exceptions: +When [receiving webhook events](/docs/webhooks.md), `context.octokit` is _usually_ an authenticated client, but there are a few events that are exceptions: - [`installation.deleted` & `installation.suspend`](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads#installation) - The installation was _just_ deleted or suspended, so we can't authenticate as the installation. @@ -102,7 +102,7 @@ If you want to run a Probot App against a GitHub Enterprise instance, you'll nee GHE_HOST=fake.github-enterprise.com ``` -When [using Probot programmatically](./development.md#run-probot-programmatically), set the `baseUrl` option for the [`Probot`](https://probot.github.io/api/latest/classes/probot.html) constructor to the full base Url of the REST API +When [using Probot programmatically](/docs/development.md#run-probot-programmatically), set the `baseUrl` option for the [`Probot`](https://probot.github.io/api/latest/classes/probot.Probot.html) constructor to the full base Url of the REST API ```js const MyProbot = Probot.defaults({ diff --git a/docs/hello-world.md b/docs/hello-world.md index 4be267492e..8c967f53f6 100644 --- a/docs/hello-world.md +++ b/docs/hello-world.md @@ -13,9 +13,9 @@ module.exports = (app) => { }; ``` -The `app` parameter is an instance of [`Probot`](https://probot.github.io/api/latest/classes/probot.html) and gives you access to all of the GitHub goodness. +The `app` parameter is an instance of [`Probot`](https://probot.github.io/api/latest/classes/probot.Probot.html) and gives you access to all of the GitHub goodness. -`app.on` will listen for any [webhook events triggered by GitHub](./webhooks.md), which will notify you when anything interesting happens on GitHub that your app wants to know about. +`app.on` will listen for any [webhook events triggered by GitHub](/docs/webhooks.md), which will notify you when anything interesting happens on GitHub that your app wants to know about. ```js module.exports = (app) => { @@ -26,7 +26,7 @@ module.exports = (app) => { }; ``` -The [`context`](https://probot.github.io/api/latest/classes/context.html) passed to the event handler includes everything about the event that was triggered, as well as some helpful properties for doing something useful in response to the event. `context.octokit` is an authenticated GitHub client that can be used to [make REST API and GraphQL calls](./github-api.md), and allows you to do almost anything programmatically that you can do through a web browser on GitHub. +The [`context`](https://probot.github.io/api/latest/classes/context.Context.html) passed to the event handler includes everything about the event that was triggered, as well as some helpful properties for doing something useful in response to the event. `context.octokit` is an authenticated GitHub client that can be used to [make REST API and GraphQL calls](/docs/github-api.md), and allows you to do almost anything programmatically that you can do through a web browser on GitHub. Here is an example of an autoresponder app that comments on opened issues: diff --git a/docs/http.md b/docs/http.md index e4a4a1b099..7583c6a450 100644 --- a/docs/http.md +++ b/docs/http.md @@ -5,7 +5,7 @@ title: HTTP routes # HTTP routes -When starting your app using `probot run ./app.js` or using the [`Server`](./development.md#use-server) class, your Probot app function will receive the `options.getRouter` function as its 2nd argument. +When starting your app using `probot run ./app.js` or using the [`Server`](/docs/development.md#use-server) class, your Probot app function will receive the `options.getRouter` function as its 2nd argument. Calling `getRouter('/my-app')` will return an [express](http://expressjs.com/) router that you can use to expose custom HTTP endpoints from your app.