A robot to make open source easy for Firebasers. The robot has multiple distinct features which can be enabled individually.
In shared repos you may only want to receive email notifications for a subset of the events that are fired. The bot allows you to specify a specific email address for each label and then you will only receive emails for issues/PRs with that label:
// In this example, the engineers on the 'foo' team will get emails
// about issues labeled 'foo' and the engineers on the 'bar' team
// will get emails about issues labeled 'bar'
"my-repo": {
"labels": {
"foo": {
"email":"[email protected]"
},
"bar":{
"email":"[email protected]"
}
}
}
The bot can automatically label incoming issues based on regex matching:
"my-repo": {
"labels": {
"foo": {
"regex":"Component:[\\s]+?[Ff]oo",
"email": // ...
},
}
}
In the example above, an issue that contains "Component: foo" or "Component: Foo" or any variation would automatically get the "foo" label. When combined with the custom emails configuration above, this means the bot can auto-label and then auto-notify the Foo engineering team about new issues or issue events.
If bot can't find a label for an issue, it will add the label needs-triage
and then
add a comment explaining to the developer that a human will come to help.
If you use issue templates on your GitHub repo, the bot can enforce that new issues match the template.
Issue templates are considered in "sections" where each section is a third-level header,
denoted in markdown by ###
. For example:
### Are you in the right place?
Are you using FooBar Engineering products? If not, go away!
### [REQUIRED] Describe your environment
* FooBar SDK Version: ____
* Operating System: ____
### [REQUIRED] Describe your problem
* What are the steps to reproduce?
* What do the logs say?
The bot does checks at two levels:
[REQUIRED]
did the developerIf the user violates either of the above checks, the bot will leave a comment telling them what they may have done wrong.
If your issue template is located at ISSUE_TEMPLATE.md
then the bot will
know where to find it without any configuration. If you want to specify a different
location for your template, add it to the config:
"my-repo": {
// ...
"templates":{
"issue":".github/ISSUE_TEMPLATE.md"
}
}
If your repo has multiple templates (like one for bugs and one for features) you must add a markdown comment to the template to let the robot know how to locate it:
<!-- DO NOT DELETE
validate_template=true
template_path=.github/ISSUE_TEMPLATE/bug.md
-->
### My first section
...
You can configure how the required sections of an issue template are validated and whether/which label is added to the issue in case of a violation:
"validation": {
"templates": {
".github/ISSUE_TEMPLATE/bug.md": {
"validation_failed_label": "need more info",
"required_section_validation": "relaxed"
},
...
}
}
There are three different levels of required section validation:
strict
: Any empty required section is a violationrelaxed
: As long as one required section is filled, it's oknone
: No validation of required sectionsThe bot can help you clean up issues that have gone "stale", meaning that more information is needed but has not been provided.
The flow is described in this chart:
The names of the labels and the length of certain time periods can be configured in your repo config:
"my-repo": {
// ...
"cleanup": {
"issue": {
// [REQUIRED] Label manually applied for issues that need more information.
"label_needs_info": "Needs Info",
// [OPTIONAL] Label to be applied for issues that need Googler attention.
// If unspecified, this state will not have a visible label.
"label_needs_attention": "Needs Attention",
// [REQUIRED] Label to be applied for issues that don't have recent activity
"label_stale": "Stale",
// [OPTIONAL] Label(s) that can be applied to issues to exempt them from the stale
// checker.
"ignore_labels": ["Feature Request", "Internal"],
// [REQUIRED] Time, in days, to stay in the needs_info state before becoming stale
// stale. These issues transition from label_needs_info to label_stale.
"needs_info_days": 7,
// [REQUIRED] Time, in days, to close an issue after the warning message is posted
// if there is no recent activity. These issues will transition from
// label_stale to closed.
"stale_days": 3,
// [OPTIONAL] Time, in days, to lock an issue after it has been closed.
"lock_days": 60
}
}
}
The bot can lock issues that have been closed for a while to prevent new discussion.
To enable this, add the lock_days
key to your "stale issue config" (see above).
The bot can send you a weekly report of how healthy your repo is. To receive this report, just add a reporting config:
"my-repo": {
// ...
"reports": {
"email": "[email protected]"
}
}
You will then receive a weekly email with:
The bot keeps a log of visible actions it takes on GitHub, which you can view on a per-repo basis:
https://ossbot.computer/audit.html?org=ORG_NAME&repo=REPO_NAME
After completing all configuration below, run make deploy
.
Edit the functions/config/config.json
file to have configuration in the following form:
{
"<ORG_NAME>": {
"<REPO_NAME>": {
// .. REPO CONFIGURATION ...
}
}
}
See the feature sections above for the different properties that can be added to the repo configuration.
Go to the github token page and create a new personal access token for the bot account with the following permissions:
public_repo
- access public repositories.admin:repo_hook
- read and write repository hooks.firebase functions:config:set github.token="<YOUR_GITHUB_TOKEN>"
firebase functions:config:set mailgun.key="<YOUR_MAILGUN_KEY>"
firebase functions:config:set mailgun.domain="<YOUR_MAILGUN_DOMAIN>"
In order to use the SendWeeklyEmail
endpoint you need to configure the
recipient to some public group.
firebase functions:config:set email.recipient="<GROUP_TO_GET_EMAILS>"
In GitHub add a webhook with the following configuration:
https://<YOURPROJECT>.cloudfunctions.net/githubWebhook
.To run basic tests, use make test-functions
which runs the mocha tests the functions
directory. These tests are mostly a sanity check, used to verify basic behavior without
needing an end-to-end deploy.
Code is formatted using prettier
so no bikeshedding allowed. Run
npm run build
in the functions
directory before committing.