Skip to content

Latest commit

 

History

History
133 lines (101 loc) · 7.59 KB

README.md

File metadata and controls

133 lines (101 loc) · 7.59 KB
Raw

statusbot

statusbot is a chat bot built on the Probot framework. A wiki is available here.

This README will help you get started. It will be updated and improved to discuss user-specific instances, usage and deployment, the functionality available, and more!

What does the bot do?

  • Background management in GitHub:
    • Assign new PRs to the Pipeline for QA project board (REVIEW column).
    • Move existing PRs to the correct Pipeline for QA project board column (REVIEW/IN TEST), depending on whether or not the required conditions are met: is mergeable, at least two reviewers have approved it, and there is no request for changes.
    • Assign issues that are labeled bounty-awaiting-approval to the Status SOB Swarm project board (bounty-awaiting-approval column).
    • Welcome users who post their first PR in a project.
    • Check whether all commits are GPG signed, and set the PR status accordingly.
    • Unfurl links on Issues and Pull Request discussions.
    • Disallow merging of PRs containing WIP in the title.
    • Mention repo collaborators on Slack when a GHI is assigned the bounty-awaiting-approval label.
    • After a PR is moved to the column specified in automated-tests/kickoff-column-name and the build has passed successfully, the bot will kick a test automation build in Jenkins (retry periodically if the PR build is still running).
    • New functionality will be added in the future, and the wishlist is being tracked here).

The project board's names, column names, welcome message, and other values are stored in the .github/github-bot.yml file. It can be overriden for each specific repository by adding a file in the same path on the respective repository (see probot-config).

Development

To get your environment set up, go through the following steps:

  1. Run yarn install.

  2. Populate .env.

    cp .env.example .env213804

# edit .env file to contain proper config

After this, you can start the bot by running the following:

yarn start

Creating the Slack Bot Integration

  1. Go to https://my.slack.com/services/new/bot.
  2. Add a bot integration.
  3. Note the bot token starting with xoxb-, and put it into .env.

Creating the bot GitHub App

This bot is meant to be packaged as a GitHub App. There are two steps to it: creating the app, and installing the app. The app needs to be created only once and can be made public and reused for any number of repositories and organizations.

See the official docs for deployment.

  1. Create the GitHub App:
    1. In GitHub, go to Settings/Developer settings/GitHub Apps and click on New GitHub App
    2. Enter the bot name in GitHub App name, e.g. Status GitHub Bot
    3. In Homepage URL, enter the /ping endpoint of the service, e.g. https://5e63b0ab.ngrok.io/ping
    4. In Webhook URL, enter the root endpoint of the service, e.g. https://5e63b0ab.ngrok.io/
    5. In Webhook secret (optional), enter a string of characters that matches the value passed in the in the WEBHOOK_SECRET environment variable.
    6. This app requires these Permissions & events for the GitHub App:
      • Commit statuses - Read & write
      • Issues - Read & Write
        • Check the box for Issue comment events
        • Check the box for Issues events
      • Pull requests - Read & Write
        • Check the box for Pull request events
        • Check the box for Pull request review events
        • Check the box for Pull request review comment events
      • Repository contents - Read-only
        • Check the box for Push events
      • Repository projects - Read & Write
        • Check the box for Project for repository projects events
        • Check the box for Project card for repository projects events
      • Organization projects - Read-only
        • Check the box for Project for organization projects events
      • Single File - Read-only
        • Path: .github/github-bot.yml
    7. 🔍 Verify that you have ticked 9 boxes.
    8. Generate a private key pass and save it.
  2. Installing the bot service:
    1. Deploy the bot to the cloud.
    2. Set the APP_ID environment variable to value reported when the GitHub App was created.
    3. Set the WEBHOOK_SECRET environment variable to the value configured in the GitHub App.
    4. Set the PRIVATE_KEY environment variable to the contents of the .pem file.
    5. Set the SLACK_BOT_TOKEN environment variable to the value reported for the bot in Slack.
  3. Install the GitHub App in an account:
    1. Select the repositories where the bot should work (e.g. status-react).

Customizing the bot

The bot gets its settings from a per-repo file located at .github/github-bot.yml. That file extends the base file at the status-im/probot-settings repo.

Examples of settings that can be configured:

  • github-team/slug: Slug of the team that owns the respective repository

  • welcome-bot/message-template: First time contributor welcome message template. Examples of template values allowed:

    • {user}: Replaced by the PR submitter's user name
    • {repo-name}: Replaced by the PR's target repository name
    • {pr-number}: Replaced by the PR number

  • slack/notification/room: Slack room used for notifications (e.g. status-probot)

  • Repository project board settings:

    • project-board/name: Name of the QA pipeline project board
    • project-board/contributor-column-name: Name of the column in the project board to group issues that are being worked on by a contributor
    • project-board/review-column-name: Name of the column in the project board to group issues that are up for review
    • project-board/test-column-name: Name of the column in the project board to group issues that up for testing by QA

  • Bounty project board settings:

    • bounty-project-board/name: Name of the bounty project board in GitHub
    • bounty-project-board/owner: GitHub username of the maintainer of the bounty project board (used to e.g. send Slack notifications)
    • bounty-project-board/awaiting-approval-column-name: Name of the column in the bounty project board to group issues that are awaiting for bounty approval
    • bounty-project-board/awaiting-approval-label-name: Name of the label used in issues to declare that an issue is awaiting approval to become a bounty
    • bounty-project-board/bounty-label-name: Name of the label used in issues to declare that an issue is a bounty
    • bounty-project-board/bounty-size-label-name-regex: Regular expression that matches the bounty size label and returns a group containing the size itself
    • bounty-project-board/post-approved-bounties-to-slack-room: Name of the Slack room where to cross-post approved bounties

  • Automated tests settings:

    • automated-tests/repo-full-name: Full name of the repo to watch in project cards in order to automatically run automated tests CI job (e.g. status-im/status-react)
    • automated-tests/job-full-name: Full name of the CI job to run automated tests (e.g. end-to-end-tests/status-app-end-to-end-tests)

Restart the bot

You may want to get comfortable with heroku logs and heroku restart if you're having issues.