Status: This project is no longer developed or maintained. GitHub Apps natively support the functionality of this package.
A React + Redux application that serves as a base for GitHub bot UIs. It manages login, provides a page to enable or disable the bot on repositories, and has extensibility points for bots that require additional settings.
Most user will consume the application as a whole, passing some properties at
the top level to customize things. You can find a working example of the
integration in the example directory and in the server.js file.
-
Add the library (and React) to your project:
npm install github-bot-ui react react-dom -
Create a minimal
index.htmlfile in which to inject the application:<!doctype html> <html> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> </head> <body> <div id="container"></div> </body> </html>
-
Create an
index.jsfile to initialize the application:import React from 'react'; import ReactDOM from 'react-dom'; import GitHubBotUi from 'github-bot-ui'; const container = document.getElementById('container'); ReactDOM.render( <GitHubBotUi appName="My Bot" gitHubUrl="https://github.com" docsUrl="https://github.com/myorg/mybot"/>, container );
-
Create a file that aggregates the dependency CSS files. Here we'll use SCSS, but you can use any method in your project:
@import "~normalize.css"; @import "~@blueprintjs/core/dist/blueprint.css"; @import "~github-bot-ui/github-bot-ui.css";Note that we're including the dependency styles from Blueprint as well.
-
Configure Webpack or another builder to compile the files and generate a bundle. Configuring Webpack is outside the scope of this guide, but you can find a working configuration in
server.js.
The UI expects the server to expose specific endpoints to function. You can
find a mock implementation of these endpoints in server.js.
Redirects to the GitHub OAuth endpoint with correct parameters. The OAuth
application should be configured to redirect to /login after authentication.
The /login route is handled github-bot-ui.
Query Parameters:
code- the GitHub OAuth codestate- the OAuth state value provided in the initial redirect
Returns an object with a token property. This property contains a
JWT for the user that just authenticated. The
token must contain the sub field, but all other fields are optional.
github-bot-ui will provide this as a Bearer token in the Authorization
header with future requests. The server usually maintains a mapping from
information in the JWT to the GitHub OAuth token for the corresponding user.
Returns a JSON list of repositories to which the user has write access and their status with the bot. Each object in the list has the following properties:
id- (number, required) a unique numeric ID for the repositoryowner- (string, required) the user or organization that owns the repositoryname- (string, required) the name of the repositoryisEnabled- (boolean, required) indicates if the bot is enabled for this repositoryisUserAdmin- (boolean, required) indicates if the current user has admin permissions on the repositoryenabledBy- (string, optional) if the bot is enabled for this repository, the name of the enabling userenabledAt- (string, optional) if the bot is enabled for this repository, the date and time at which it was enabled, in RFC3339/ISO8601 format.
Enables the bot for a repository. On success, returns 200 OK with a JSON
representation of the repository as described above.
Disables the bot for a repository. On success, returns 204 No Content.