Firebase OSS Robot

Introduction

A robot to make open source easy for Firebasers. The robot has multiple distinct features which can be enabled individually.

Custom Emails

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]"
    }
  }
}

Issue Labeling

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.

Template Matching

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:

Template Integrity - did the developer filling out the template leave all the headers in place? If not, we can't easily parse the content.
Required Sections - for any section marked with [REQUIRED] did the developer make at least some change to the content of the section?

If 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
...

Template validation

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 violation
relaxed: As long as one required section is filled, it's ok
none: No validation of required sections

Stale Issue Cleanup

The 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
    }
  }
}

Old Issue Locking

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).

Repo Reports

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:

Change in open issues, stars, and forks.
List of which issues were opened in the past week.
List of which issues were closed in the past week.

Monitoring

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

Deployment

Deploy Functions, Configuration, and Cron Jobs

After completing all configuration below, run make deploy.

Customize Configuration

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.

Configure Secrets

GitHub:

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>"

Mailgun:

firebase functions:config:set mailgun.key="<YOUR_MAILGUN_KEY>"
firebase functions:config:set mailgun.domain="<YOUR_MAILGUN_DOMAIN>"

Email

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>"

Configure GitHub Webhook

In GitHub add a webhook with the following configuration:

Payload URL - your cloud functions HTTP URL. Which should be https://<YOURPROJECT>.cloudfunctions.net/githubWebhook.
Content type - application/json
Secret - N/A
Select individual events:
- Issues
- Pull request
- Issue comment

Development

Test

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.

Formatting

Code is formatted using prettier so no bikeshedding allowed. Run npm run build in the functions directory before committing.

isabella232 / oss-bot Goto Github PK

oss-bot's Introduction