Hello! I'm Cesium Concierge, a GitHub bot for Cesium. I automate common GitHub tasks such as welcoming first time contributors and reminding you to write tests. (I'm great fun at parties!)
You'll find repository-specific settings in each repository I watch under a .concierge
directory. For example, here's CesiumJS's concierge settings:
https://github.com/CesiumGS/cesium/tree/main/.concierge
Clone this repository:
$ git clone https://github.com/CesiumGS/cesium-concierge
Install the dependencies:
$ cd cesium-concierge && npm install
And run:
$ npm start
cesium-concierge
requires a few configuration settings before working. These are loaded, in the following order of priority, from:
- The repository's
.concierge/config.json
file. - Environment variables.
- Built-in defaults.
The table below describes all the possible configuration variables, as well as their default values if any.
Name | Type | Description | Required? | Default |
---|---|---|---|---|
secret |
string |
Repository secret to verify incoming WebHook requests from GitHub | ✓ | |
repositories:{full_name} |
object |
Settings specific to the repository {full_name} . |
✓ | |
repositories:{full_name}:gitHubToken |
string |
Token used to verify outgoing requests to GitHub repository | ✓ | |
repositories:{full_name}:thirdPartyFolders |
string |
Comma-separated list of folders in which to look for changed files in pull request to remind user to update License. | X | [] |
repositories:{full_name}:contributorsPath |
string |
Relative path from the root of the repository to the CONTRIBUTORS.md file. |
X | Disabled if not set. |
repositories:{full_name}:contributorsFromGitHub |
string |
Use the GitHub Contributors API to check for previous contributors to the repository. | X | Disabled if not set. |
repositories:{full_name}:maxDaysSinceUpdate |
number |
"Bump" pull requests older than this number of days ago. | X | 30 |
repositories:{full_name}:unitTestPath |
string |
Relative path to the directory containing unit tests. Example:Specs/ |
X | Disabled if not set. |
googleApiConfig |
string |
Google API config for reading the list of CLA signers from Google Sheets. See CLA checking for full instructions. | X | Disabled if not set. |
individualClaSheetID |
string |
The ID of the Google Sheets storing the signed CLA information for individual contributors. See CLA checking for full instructions. | X | Disabled if not set. |
corporateClaSheetID |
string |
The ID of the Google Sheets storing the signed CLA information for corporate contributors. See CLA checking for full instructions. | X | Disabled if not set. |
port |
number |
Port on which to listen to incoming requests. | X | 5000 |
listenPath |
string |
Path on which to listen for incoming requests. | X | "/" |
slackToken |
string |
Slack API token for posting release reminders and fun stats to the Slack team. | X | Disabled if not set. |
slackConfigUrl |
string |
The GitHub API URL to a YAML file containing the release schedule and other SlackBot config. | X | "" |
Note:
full_name
is the repository name in the form{organization}/{repository}
. For example:CesiumGS/cesium
secret
and repositories:{full_name}:gitHubToken
are the important settings; they verify that the communication between your server and
GitHub is safe.
Enable a GitHub WebHook on a repository, making sure to create a secret. The secret verifies that all incoming requests to your server are from GitHub and not something else.
Next, get a Personal Access Token, which verifies with GitHub that all requests to its API come from an account with privileges. Set it locally by using any of the three ways listed above.
See "installing a bot" on Slack's Enabling interactions with bots guide.
Concierge can automate the CLA (contribute license agreement) process. Here's how it works:
- New contributor electronically signs agreement using a Google form.
- This form automatically outputs to a Google spreadsheet.
- Concierge checks this spreadsheet on every new pull request to see if that contributor's GitHub username is in the sheet.
Assuming you already have a Google form setup, all you need to do is configure:
individualClaSheetID
- this is the spreadsheet ID for form responses for the individual CLA agreement. Concierge expects column D to be the GitHub username.- You can find the spreadsheet ID from the URL, which is in the form of
https://docs.google.com/spreadsheets/d/<id>/edit
.
- You can find the spreadsheet ID from the URL, which is in the form of
corporateClaSheetID
- same as above, but for the corporate CLA agreement. Concierge expects column H to be the Schedule A response, which is a list of names of employees along with their GitHub usernames. This is loosely formatted, so Concierge checks if the new PR author's username is a substring of that column.googleApiConfig
- this is the JSON content of the credentials file from the Google service account, see Google's authentication guide for getting this configuration.- When you set up a new Service account, you'll be able to download the key, which includes a project id, a private key, and some other metadata. The contents of this file can be supplied as the value of this environment variable.
- Note that you must also allow this Service account to have view access to the two spreadsheets above. You can do this by inviting the Service account email to have access to the Google spreadsheet (you can find this email from the Google Cloud Platform console, which should look something like
[email protected]
).