Your team uses Basecamp. And your team hosts code in a GitHub organization. Basecamp provides a basic chatbot for GitHub, but that requires manual setup for each repository, and only provides notifications for commits.
Basecamp + Github Chatbot provides teams with a simple solution for customizable notifications of all GitHub repository events!
The bot has simple commands for managing the repositories subscribed to by a given Campfire. Each Campfire can subscribe to as many repositories as necessary for the team or project. You can even ping the bot for private updates.
Example interaction
The bot works at the organization level of GitHub. This means that once you have your webhooks configured, no additional setup will be required to receive updates for new or deleted repositories.
Using ejs templates, the repository notification messages can be customized to suit your needs. Any repository event from this list is supported.
- A public-facing server with Docker, Docker Compose, and Node.js installed to be able to build the Docker image.
- Basecamp 3
- GitHub organization
- Admin rights on both Basecamp and Github (setup only)
Copy .env.example to .env. Set the following keys appropriately:
| Key | Value | Example |
|---|---|---|
SERVER_PORT |
the port to run the server on | 3000 (default) |
BASECAMP_ACCESS_KEY |
an access key of your choice to prevent abuse | (see below) |
BASECAMP_USER_AGENT |
user agent to use when making requests to the Basecamp API [note] | Your-Org-Bot (your-email@example.org) |
GITHUB_HMAC_SECRET |
20 character hex key also provided to GitHub | (see below) |
GITHUB_ORGANIZATION |
GitHub organization name | your-github-org-name |
DATA_DIRECTORY |
Where to store database and logs. Default .. |
data |
Here are some good ways to generate your HMAC secret and access key:
$ ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
477c9451ca82b8534e4f5efd0ab5d5ee9690318a
$ hexdump -n 20 -e '20/1 "%02x" 1 "\n"' /dev/urandom
7ff37aac0ef32709ed0341c61430fe6a3b71a03d
You have 2 choices on how to run the application: Docker (recommended and tested), or Node.js.
If you would like to run your server in a Docker container, you only need .env, and optionally docker-compose.yml.
To simplify things, the default docker-compose.yml will run a single container, passing the environment variables in .env. By default the error log will be stored in the current local directory as error.log, and the database as database.json.
See the relevant comment in the volumes section of docker-compose.yml for help supplying your own message templates.
$ docker-compose -f docker-compose.yml up
# or
$ docker-compose -f docker-compose.yml up -d # detached
To run without Docker Compose, use a command similar to the following:
$ docker run --env-file=.env -p 3000:3000 -v $(pwd)/error.log:/home/app/error.log -v $(pwd)/database.json:/home/app/database.json foundersclubsoftware/basecamp-github-chatbot:latest
If you plan to run Node directly on your server and not use Docker, simply build and run on your server after setting your environment variables:
$ npm install
$ npm run _build
$ npm run _production:run
Errors are logged to error.log when running in production, and the database is stored in database.json.
In your GitHub organization, go to Settings→Webhooks→Add webhook.
Webhook setup
| Field | Value |
|---|---|
| Payload URL | https://<your-server-host>/hook |
| Content type | application/json |
| Secret | The value of GITHUB_HMAC_SECRET in your .env |
Select the events you would like to receive, then click Add webhook.
In any bucket in Basecamp, click the ellipsis in the upper right corner and select Configure chatbots→Add new chatbot.
Webhook setup
| Field | Value |
|---|---|
| Avatar (optional) | this project's icon |
| Name | ghub or however you wish to address your bot |
| Command URL | https://<your-server-host>/command?access_key=<your-access-key> |
Click Add this chatbot and you're ready to go!
Interact with the bot by chatting !<bot-name> <command> in any campfire. Available commands are:
| Command | Action |
|---|---|
help |
provides a brief summary of commands |
subscribe <repo> |
subscribes the current Campfire to notifications for <repo> |
unsubscribe <repo> |
unsubscribes the current Campfire to notifications for <repo> |
list |
list the repositories the current Campfire is subscribed to |
When subscribing or unsubscribing, omit the organization prefix (e.g. repo instead of myorg/repo).
If you would like to add support for other events or change the message templates, edit the notifications key of templates.json. Place your modified templates.json in your data directory, alongside where the database is stored. Any events listed here are supported. If you limited your webhook on Github to certain events, you may need to update its scope.
Notification entries are of the form
"event_name": {
"templates": {
"hello": "<a href='hello'>hello</a>"
}
"actions": {
"created": "<%- hello %> there",
"default": "default message"
}
}
where event_name is the GitHub webhook event name, and the keys of actions match the possible values of action in the webhook payload. The default value is used when a payload's action doesn't match any of the other keys. If the value of an action is an empty string, no message will be sent.
The templates key defines snippets that can be reused in the messages for each action of an event, as seen above. Both templates and actions use ejs to render each message. The entire webhook payload object is available for use in your templates and messages. Examples of payload objects for each event type are available here.
The entries in the responses key of templates.json can be edited to modify the responses of the bot to user commands.
You will need Docker and Node.js installed on your machine to develop for the bot.
You can use ngrok or a similar service to forward a server on your local machine to the public internet.
To run the application locally on your machine in development mode:
$ npm run dev:build
$ npm run dev:run
If you find bugs or have a request, create an issue. If you would like to contribute, feel free to submit a pull request!
- Levi Bostian @levibostian
- Oliver Emery @thrymgjol
Basecamp + GitHub Chatbot is available under version 2.0 of the Apache license.
University of Iowa Founders Club · Website · GitHub @foundersclubsoftware