forked from mirrors/probot
Merge pull request #154 from probot/github-app
Update name to "GitHub Apps"
This commit is contained in:
Brandon Keepers
GitHub
commit
7b28802eb6
|
|
@ -1,5 +1,5 @@
|
|||
# The ID of your GitHub integration
|
||||
INTEGRATION_ID=
|
||||
# The ID of your GitHub App
|
||||
APP_ID=
|
||||
WEBHOOK_SECRET=development
|
||||
|
||||
# Uncomment this to get verbose logging
|
||||
|
|
|
|||
|
|
@ -2,13 +2,9 @@
|
|||
|
||||
Probot is a bot framework for GitHub. It's like [Hubot](https://hubot.github.com/), but for GitHub instead of chat.
|
||||
|
||||
If you've ever thought, "wouldn't it be cool if GitHub could…"; imma stop you right there. Most features can actually be added via [GitHub Integrations](https://developer.github.com/early-access/integrations/):
|
||||
If you've ever thought, "wouldn't it be cool if GitHub could…"; imma stop you right there. Most features can actually be added via [GitHub Apps](https://developer.github.com/apps/), which extend GitHub and can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. Apps are first class actors within GitHub.
|
||||
|
||||
> Integrations are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. Integrations are first class actors within GitHub.
|
||||
>
|
||||
> –Documentation on [GitHub Integrations](https://developer.github.com/early-access/integrations/)
|
||||
|
||||
There are some great services that offer [hosted integrations](https://github.com/integrations), but you can build a bunch of really cool things yourself. Probot aims to make that easy.
|
||||
There are some great services that offer [apps in the GitHub Marketplace](https://github.com/marketplace), and you can build a bunch of really cool things yourself. Probot aims to make that easy.
|
||||
|
||||
## Plugins
|
||||
|
||||
|
|
|
|||
8
app.json
8
app.json
|
|
@ -6,13 +6,13 @@
|
|||
"logo": "https://github.com/probot.png",
|
||||
"env": {
|
||||
"PRIVATE_KEY": {
|
||||
"description": "the private key you downloaded when creating the GitHub Integration"
|
||||
"description": "the private key you downloaded when creating the GitHub App"
|
||||
},
|
||||
"INTEGRATION_ID": {
|
||||
"description": "the ID of your GitHub Integration"
|
||||
"APP_ID": {
|
||||
"description": "the ID of your GitHub App"
|
||||
},
|
||||
"WEBHOOK_SECRET": {
|
||||
"description": "the secret configured for your GitHub Integration"
|
||||
"description": "the secret configured for your GitHub App"
|
||||
},
|
||||
"LOG_LEVEL": {
|
||||
"required": false,
|
||||
|
|
|
|||
|
|
@ -9,15 +9,25 @@ const {findPrivateKey} = require('../lib/private-key');
|
|||
|
||||
program
|
||||
.usage('[options] <plugins...>')
|
||||
.option('-i, --integration <id>', 'ID of the GitHub Integration', process.env.INTEGRATION_ID)
|
||||
.option('-s, --secret <secret>', 'Webhook secret of the GitHub Integration', process.env.WEBHOOK_SECRET || 'development')
|
||||
.option('-i, --integration <id>', 'DEPRECATED: ID of the GitHub App', process.env.APP_ID)
|
||||
.option('-a, --app <id>', 'ID of the GitHub App', process.env.APP_ID)
|
||||
.option('-s, --secret <secret>', 'Webhook secret of the GitHub App', process.env.WEBHOOK_SECRET || 'development')
|
||||
.option('-p, --port <n>', 'Port to start the server on', process.env.PORT || 3000)
|
||||
.option('-P, --private-key <file>', 'Path to certificate of the GitHub Integration', findPrivateKey)
|
||||
.option('-P, --private-key <file>', 'Path to certificate of the GitHub App', findPrivateKey)
|
||||
.option('-t, --tunnel <subdomain>', 'Expose your local bot to the internet', process.env.SUBDOMAIN || process.env.NODE_ENV !== 'production')
|
||||
.parse(process.argv);
|
||||
|
||||
if (!program.integration) {
|
||||
console.warn('Missing GitHub Integration ID.\nUse --integration flag or set INTEGRATION_ID environment variable.');
|
||||
if (program.integration) {
|
||||
// FIXME: remove in v0.7.0
|
||||
console.warn(
|
||||
`DEPRECATION: The --integration flag and APP_ID environment variable are\n` +
|
||||
`deprecated. Use the --app flag or set APP_ID environment variable instead.`
|
||||
);
|
||||
program.app = program.integration;
|
||||
}
|
||||
|
||||
if (!program.app) {
|
||||
console.warn('Missing GitHub App ID.\nUse --app flag or set APP_ID environment variable.');
|
||||
program.help();
|
||||
}
|
||||
|
||||
|
|
@ -56,7 +66,7 @@ function setupTunnel() {
|
|||
const createProbot = require('../');
|
||||
|
||||
const probot = createProbot({
|
||||
id: program.integration,
|
||||
id: program.app,
|
||||
secret: program.secret,
|
||||
cert: program.privateKey,
|
||||
port: program.port
|
||||
|
|
|
|||
|
|
@ -2,47 +2,47 @@
|
|||
|
||||
Every plugin can either be deployed as a stand-alone bot, or combined with other plugins in one deployment.
|
||||
|
||||
> **Heads up!** Note that most [plugins in the @probot organization](https://github.com/search?q=topic%3Aprobot-plugin+org%3Aprobot&type=Repositories) have an official hosted integration that you can use for your open source project. Use the hosted instance if you don't want to deploy your own.
|
||||
> **Heads up!** Note that most [plugins in the @probot organization](https://github.com/search?q=topic%3Aprobot-plugin+org%3Aprobot&type=Repositories) 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 Integration](#create-the-github-integration)
|
||||
1. [Create the GitHub App](#create-the-github-app)
|
||||
1. [Deploy the plugin](#deploy-the-plugin)
|
||||
1. [Heroku](#heroku)
|
||||
1. [Now](#now)
|
||||
1. [Combining plugins](#combining-plugins)
|
||||
|
||||
## Create the GitHub Integration
|
||||
## Create the GitHub App
|
||||
|
||||
Every deployment will need an [Integration](https://developer.github.com/early-access/integrations/).
|
||||
Every deployment will need an [App](https://developer.github.com/apps/).
|
||||
|
||||
1. [Create a new GitHub Integration](https://github.com/settings/integrations/new) with:
|
||||
1. [Create a new GitHub App](https://github.com/settings/apps/new) with:
|
||||
- **Homepage URL**: the URL to the GitHub repository for your plugin
|
||||
- **Webhook URL**: Use `https://example.com/` for now, we'll come back in a minute to update this with the URL of your deployed plugin.
|
||||
- **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 plugin.
|
||||
- **Permissions & events**: See `docs/deploy.md` in the plugin for a list of the permissions and events that it needs access to.
|
||||
|
||||
1. Download the private key from the Integration.
|
||||
1. Download the private key from the app.
|
||||
|
||||
1. Make sure that you click the green **Install** button on the top left of the integration page. This gives you an option of installing the integration on all or a subset of your repositories.
|
||||
1. 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 plugin
|
||||
|
||||
To deploy a plugin to any cloud provider, you will need 3 environment variables:
|
||||
|
||||
- `INTEGRATION_ID`: the ID of the integration, which you can get from the [integration settings page](https://github.com/settings/integrations).
|
||||
- `WEBHOOK_SECRET`: the **Webhook Secret** that you generated when you created the integration.
|
||||
- `APP_ID`: the ID of the app, which you can get from the [app settings page](https://github.com/settings/apps).
|
||||
- `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 integration, OR...
|
||||
- `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`.
|
||||
|
||||
### Heroku
|
||||
|
||||
Probot runs like [any other Node app](https://devcenter.heroku.com/articles/deploying-nodejs) on Heroku. After [creating the GitHub Integration](#create-the-github-integration):
|
||||
Probot runs like [any other Node app](https://devcenter.heroku.com/articles/deploying-nodejs) on Heroku. After [creating the GitHub App](#create-the-github-app):
|
||||
|
||||
1. Make sure you have the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) client installed.
|
||||
|
||||
|
|
@ -55,11 +55,11 @@ Probot runs like [any other Node app](https://devcenter.heroku.com/articles/depl
|
|||
http://arcane-lowlands-8408.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git
|
||||
Git remote heroku added
|
||||
|
||||
1. Go back to your [integration settings page](https://github.com/settings/integrations) and update the **Webhook URL** to the URL of your deployment, e.g. `http://arcane-lowlands-8408.herokuapp.com/`.
|
||||
1. Go back to your [app settings page](https://github.com/settings/apps) and update the **Webhook URL** to the URL of your deployment, e.g. `http://arcane-lowlands-8408.herokuapp.com/`.
|
||||
|
||||
1. Configure the Heroku app, replacing the `INTEGRATION_ID` and `WEBHOOK_SECRET` with the values for those variables, and setting the path for the `PRIVATE_KEY`:
|
||||
1. 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 INTEGRATION_ID=aaa \
|
||||
$ heroku config:set APP_ID=aaa \
|
||||
WEBHOOK_SECRET=bbb \
|
||||
PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
|
||||
|
||||
|
|
@ -76,19 +76,19 @@ Your plugin should be up and running!
|
|||
|
||||
### Now
|
||||
|
||||
Zeit [Now](http://zeit.co/now) is a great service for running Probot plugins. After [creating the GitHub Integration](#create-the-github-integration):
|
||||
Zeit [Now](http://zeit.co/now) is a great service for running Probot plugins. After [creating the GitHub App](#create-the-github-app):
|
||||
|
||||
1. Install the now CLI with `npm i -g now`
|
||||
|
||||
1. Clone the plugin that you want to deploy. e.g. `git clone https://github.com/probot/stale`
|
||||
|
||||
1. Run `now` to deploy, replacing the `INTEGRATION_ID` and `WEBHOOK_SECRET` with the values for those variables, and setting the path for the `PRIVATE_KEY`:
|
||||
1. Run `now` to deploy, replacing the `APP_ID` and `WEBHOOK_SECRET` with the values for those variables, and setting the path for the `PRIVATE_KEY`:
|
||||
|
||||
$ now -e INTEGRATION_ID=aaa \
|
||||
$ now -e APP_ID=aaa \
|
||||
-e WEBHOOK_SECRET=bbb \
|
||||
-e PRIVATE_KEY="$(cat ~/Downloads/*.private-key.pem)"
|
||||
|
||||
1. Once the deploy is started, go back to your [integration settings page](https://github.com/settings/integrations) and update the **Webhook URL** to the URL of your deployment (which `now` has kindly copied to your clipboard).
|
||||
1. Once the deploy is started, go back to your [app settings page](https://github.com/settings/apps) and update the **Webhook URL** to the URL of your deployment (which `now` has kindly copied to your clipboard).
|
||||
|
||||
Your plugin should be up and running!
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
# Development
|
||||
|
||||
To run a plugin locally, you'll need to create a GitHub Integration and configure it to deliver webhooks to your local machine.
|
||||
To run a plugin locally, you'll need to create a GitHub App and configure it to deliver webhooks to your local machine.
|
||||
|
||||
1. Make sure you have a recent version of [Node.js](https://nodejs.org/) installed
|
||||
1. [Create a new GitHub Integration](https://github.com/settings/integrations/new) with:
|
||||
1. [Create a new GitHub App](https://github.com/settings/apps/new) with:
|
||||
- **Webhook URL**: Set to `https://example.com/` and we'll update it in a minute.
|
||||
- **Webhook Secret:** `development`
|
||||
- **Permissions & events** needed will depend on how you use the bot, but for development it may be easiest to enable everything.
|
||||
1. Download the private key and move it to the project directory
|
||||
1. Edit `.env` and set `INTEGRATION_ID` to the ID of the integration you just created.
|
||||
1. Edit `.env` and set `APP_ID` to the ID of the app you just created.
|
||||
1. Run `$ npm start` to start the server, which will output `Listening on https://yourname.localtunnel.me`;
|
||||
1. Update the **Webhook URL** in the [integration settings](https://github.com/settings/integrations) to use the `localtunnel.me` URL.
|
||||
1. Update the **Webhook URL** in the [app settings](https://github.com/settings/apps) to use the `localtunnel.me` URL.
|
||||
|
||||
You'll need to create a test repository and install your Integration by clicking the "Install" button on the settings page of your integration.
|
||||
You'll need to create a test repository and install your app by clicking the "Install" button on the settings page of your app.
|
||||
|
||||
Whenever you come back to work on the app after you've already had it running once, you should only need to run `$ npm start`.
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ module.exports = robot => {
|
|||
|
||||
## Interacting with GitHub
|
||||
|
||||
Probot uses [GitHub Integrations](https://developer.github.com/early-access/integrations/). An integration is a first-class actor on GitHub, like a user (e.g. [@defunkt](https://github/defunkt)) or a organization (e.g. [@github](https://github.com/github)). The integration is given access to a repository or repositories by being "installed" on a user or organization account and can perform actions through the API like [commenting on an issue](https://developer.github.com/v3/issues/comments/#create-a-comment) or [creating a status](https://developer.github.com/v3/repos/statuses/#create-a-status).
|
||||
Probot uses [GitHub Apps](https://developer.github.com/apps/). An app is a first-class actor on GitHub, like a user (e.g. [@defunkt](https://github/defunkt)) or a organization (e.g. [@github](https://github.com/github)). The app is given access to a repository or repositories by being "installed" on a user or organization account and can perform actions through the API like [commenting on an issue](https://developer.github.com/v3/issues/comments/#create-a-comment) or [creating a status](https://developer.github.com/v3/repos/statuses/#create-a-status).
|
||||
|
||||
`context.github` is an authenticated GitHub client that can be used to make API calls. It is an instance of the [github Node.js module](https://github.com/mikedeboer/node-github), which wraps the [GitHub API](https://developer.github.com/v3/) and allows you to do almost anything programmatically that you can do through a web browser.
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ module.exports = robot => {
|
|||
}
|
||||
```
|
||||
|
||||
See the [full API docs](https://mikedeboer.github.io/node-github/) to see all the ways you can interact with GitHub. Some API endpoints are not available on GitHub Integrations yet, so check [which ones are available](https://developer.github.com/early-access/integrations/available-endpoints/) first.
|
||||
See the [full API docs](https://mikedeboer.github.io/node-github/) to see all the ways you can interact with GitHub. Some API endpoints are not available on GitHub Apps yet, so check [which ones are available](https://developer.github.com/v3/apps/available-endpoints/) first.
|
||||
|
||||
### Pagination
|
||||
|
||||
|
|
@ -75,15 +75,15 @@ context.github.paginate(context.github.issues.getAll(context.repo()), res => {
|
|||
|
||||
## Running plugins
|
||||
|
||||
Before you can run your plugin against GitHub, you'll need to set up your [development environment](development.md) and configure a GitHub Integration for testing. You will need the ID and private key of a GitHub Integration to run the bot.
|
||||
Before you can run your plugin against GitHub, you'll need to set up your [development environment](development.md) and configure a GitHub App for testing. You will need the ID and private key of a GitHub App to run the bot.
|
||||
|
||||
Once you have an integration created, install `probot`:
|
||||
Once you have an app created, install `probot`:
|
||||
|
||||
```
|
||||
$ npm install -g probot
|
||||
```
|
||||
|
||||
and run your bot from your plugin's directory, replacing `9999` and `private-key.pem` below with the ID and path to the private key of your integration.
|
||||
and run your bot from your plugin's directory, replacing `9999` and `private-key.pem` below with the ID and path to the private key of your app.
|
||||
|
||||
```
|
||||
$ probot run -i 9999 -P private-key.pem ./index.js
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ function findPrivateKey(filepath) {
|
|||
if (foundPath) {
|
||||
return findPrivateKey(foundPath);
|
||||
}
|
||||
throw new Error(`Missing private key for GitHub Integration. Please use:
|
||||
throw new Error(`Missing private key for GitHub App. Please use:
|
||||
* \`--private-key=/path/to/private-key\` flag, or
|
||||
* \`PRIVATE_KEY\` environment variable, or
|
||||
* \`PRIVATE_KEY_PATH\` environment variable
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ class Robot {
|
|||
*
|
||||
* @param {number} [id] - ID of the installation, which can be extracted from
|
||||
* `event.payload.installation.id`. If called without this parameter, the
|
||||
* client wil authenticate [as the integration](https://developer.github.com/early-access/integrations/authentication/#as-an-integration)
|
||||
* client wil authenticate [as the integration](https://developer.github.com/apps/authentication/#as-an-integration)
|
||||
* instead of as a specific installation, which means it can only be used for
|
||||
* [integration APIs](https://developer.github.com/v3/integrations/).
|
||||
*
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@ describe('private-key', function () {
|
|||
|
||||
it('should throw an error', function () {
|
||||
expect(findPrivateKey)
|
||||
.toThrow(Error, /missing private key for github integrationy/i);
|
||||
.toThrow(Error, /missing private key for GitHub App/i);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Reference in New Issue