status-im
/
status-github-bot
mirror of https://github.com/status-im/status-github-bot.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
status-github-bot/README.md

7.3 KiB
Raw Blame History

statusbot

statusbot is a chat bot built on the Probot framework. There's a wiki available here.

This README is intended to help get you started. Definitely update and improve to talk about your own instance, how to use and deploy, what functionality is available, etc!

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 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.
    • Checks if all commits are GPG-signed and sets the PR status accordingly.
    • Unfurls links on Issues and Pull Request discussions.
    • Disallows merging of PRs containing WIP in the title.
    • Mention repo collaborators on Slack when a GHI is assigned the bounty-awaiting-approval label.
    • When a PR is moved to the IN TEST column and the build has passed successfully, then the bot will kick a test automation build in Jenkins (retrying periodically if the PR build is still running).
    • New functionality will be added in the future (wishlist is being tracked here)

The project board 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 npm install

  2. Populate .env

    cp .env.example .env
# edit .env file to contain proper config

After this you can start the bot by running:

npm 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. Creating a GitHub App only needs to be done once and the app can be made public to be 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

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