Skip to content

Latest commit

 

History

History
119 lines (94 loc) · 5.75 KB

README.md

File metadata and controls

119 lines (94 loc) · 5.75 KB
Raw

AMP Owners Bot

A GitHub App that suggests approvers for a GitHub pull request based on OWNERS files and enforces reviews by OWNERS as a GitHub status check.

This app runs on an instance of Google AppEngine and is currently installed on ampproject/amphtml. It can be deployed to other organizations and repositories.

Status/Info Pages

  • /status: Displays the status of the app and links to other pages
  • /example: Shows the example OWNERS file syntax specification
  • /tree: Displays the current ownership tree
  • /teams: Displays the list of known teams and their members

Webhooks

The app subscribes to the following GitHub Webhooks:

  • PullRequestEvent
    • opened: run the owners check and add owners as reviewers
    • synchronize: re-run the owners check
    • closed: update the owners tree for changed OWNERS files
  • PullRequestReviewEvent
    • submitted: re-run the owners check
  • CheckRunEvent
    • rerequested: re-run the owners check
  • MembershipEvent
    • added: update the local cache of organization team members
    • removed: update the local cache of organization team members
  • TeamEvent
    • created: update the local cache of organization team members
    • edited: update the local cache of organization team members
    • deleted: update the local cache of organization team members

Cron Tasks

The app provides cron endpoints (reachable only via Google App Engine Cron Jobs):

  • /_cron/refreshTree: Re-fetches the list of OWNERS files, updates any caches, and re-parses the ownership tree
  • /_cron/refreshTeams: Re-fetches the list of teams and team members

CI Testing API

The app has an API endpoint which may be called from CI builds while testing owners files.

  • /v0/syntax
    • Accepts a payload with a path to an owners file and the contents of the file, and responds with {requestErrors, fileErrors, rules} results from parsing the OWNERS file being checked.

Setup

  1. Clone this repository and cd into the owners directory.
  2. npm install
  3. Start a new Smee channel. This can be used to proxy GitHub webhooks to your local machine.
  4. Create a new GitHub App with the following settings:
    • General
      • Set Homepage URL to the App Engine instance URL
      • Set Webhook URL to the Smee channel (development) or the App Engine instance URL (production)
      • Set Webhook Secret to any pin of your choice
    • Permissions and Events
      • Set Checks to Read & write
      • Set Pull requests to Read & write
      • Set Commit statuses to Read & write
      • Set Contents to Read-only
      • Set Issues to Read-only
      • Set Metadata to Read-only
      • Set Members to Read-only
      • Subscribe to events: Check run, Pull request, Pull request review, Team, and Membership
  5. After creating the application, generate and download a private key. Also take note of the App ID.
  6. Create a personal access token belonging to a GitHub user with the public_repo, read:org, and repo:status permissions and note its access token.
  7. Install the application on a GitHub repository that you want to use for testing. You might want to fork the ampproject/amphtml repository or create a new repository for this purpose.
  8. Create a Cloud Storage Bucket and generate a JSON credential file for a service account with Storage Object Admin permissions on the bucket.
  9. Copy the .env.example file to .env and modify the fields based on the instructions in that file and the values from the GitHub App page:
    • The value for the APP_ID field is the App ID from Step 5.
    • The value for WEBHOOK_SECRET is the secret you set when creating the GitHub app.
    • The value for the PRIVATE_KEY field is a base64 representation of the .pem file you downloaded from the GitHub App page in Step 5. On Linux/Mac you can convert that file by running cat private-key-file.pem | base64 in a command line.
    • The value for GITHUB_ACCESS_TOKEN is the token generated in step 6.
    • The value for CLOUD_STORAGE_BUCKET is the name of the Cloud Storage bucket created in Step 8
    • Update the remaining fields for the organization, repository, and bot for which you are running the app.
  10. Warm up the file cache with npm run init

If there are no errors after running the last command then the server is running locally on your machine.

Local Development

If you need to receive webhooks locally, make sure the app in GitHub is configured to use the Smee channel as the webhook URL. Set the env variable WEBHOOK_PROXY_URL to the Smee channel.

For Cloud Storage access locally, you'll need to set the env variable GOOGLE_APPLICATION_CREDENTIALS to an absolute path to the JSON credential file for the service account for the storage bucket.

To run the app locally, run npm run start. To run just the info server locally, run npm run dev.

Deployment

After setting up the app locally, use gcloud to deploy the app and cron tasks:

  1. gcloud init
  2. gcloud app deploy app.yaml
  3. gcloud app deploy cron.yaml

This GitHub App is deployed on an AppEngine instance: https://ampproject-owners-bot.appspot.com/