probot/README.md

PRobot

NOTE: this REAME is aspirational, and the project name is guaranteed to change.

PRobot is a trainable robot that responds to activity on GitHub. It's like Hubot, but for GitHub events instead of chat messages.

Automatically welcome first-time contributors, @mention previous authors, or close stale pull requests with pre-built behaviors. Write your own behaviors to implement whatever workflow your project needs.

Why?

Almost any workflow or process you can imagine can be added to GitHub with webhooks, the API, and now Integrations. But adding that workflow usually involves writing a lot of code to integrate with GitHub, and a tiny bit of code to implement the behavior you want. This project aims to be a generic bot for building integrations with GitHub.

The functionality of all of these awesome bots could be ported to behaviors:

• highfive - GitHub hooks to provide an encouraging atmosphere for new contributors
• Homu - A bot that integrates with GitHub and your favorite continuous integration service
• mention-bot - Automatically mention potential reviewers on pull requests.
• PullAprove
• LGTM
• Auto-reply
• Know of other examples? Add them here…

Here are some behaviors that we plan to implement:

• Auto-responder for new issues and pull requests
• Welcome new contributors
• Auto close stale PRs
• @mention OWNERS based on modified files
• "Based on recent activity, expect a response in X days"

Installing

TODO: install the hosted integration into your organization / account

TODO: deploy your own bot

Configuring

Behaviors are configured in a file called .probot.yml in the repository. They are composed of 3 parts:

• on - webhook events to listen to
• when (optional) - conditions to determine if the actions should be performed
• then - actions to take in response to the event

Here are a few examples:

behaviors:

# Post welcome message for new contributors
- on:
    # These are the webhook event and the "action"
    # https://developer.github.com/webhooks/#events
    - issues.opened
    - pull_request.opened
  when:
    first_time_contributor: true # plugins could implement conditions like this
  then:
    # Post a comment on the issue or pull request with the template, which can
    # use variables from the webhook event.
    comment:
      from_file: .github/NEW_CONTRIBUTOR_TEMPLATE.md

# Tweet when a new release is created
- on: release.published
  then:
    tweet: "Get it while it's hot! {{ repository.name }} {{ release.name }} was just released! {{ release.html_url }}"

# Assign a reviewer issues or pull requests with a label
- on:
    - issues.opened
    - pull_request.opened
    - issues.labeled
    - pull_request.labeled
  when:
    label: security
  then:
    assign:
      random:
        from_team: security-first-responders

Any conceivable condition (when) or action (then) could be implemented by plugins. See Configuration for more information on what behaviors can be built.