pr-triage-syncer

Populate useful fields on a GitHub project board so maintainers can triage open PRs better.

Some example project boards that result from this bot are:

• JupyterHub
• JupyterLab
• GeoJupyter

What is this?

Please see this blog post for more information while we fill out this section of the README.

Principles

This section iterates the general principles that inform the design and operation of this bot.

1. The bot owns the following:

   1. The schema of the Project Fields
   2. The values of the project fields for all PRs that have been added to the board

   Any changes humans make to those will be reverted by the bot the next time it runs.

   It currently does not own the following:

   1. The various views (tabs) in the Project Board, as these are more specific to each project's humans and what they find useful.

   Changes to that are not reverted by the bot the next time it runs.

2. The calculation of the values for Project Fields should be all deterministic, so they are stable between runs as long as the PR itself doesn't change.

3. The bot should be useable across many different GitHub organizations, so should have no knowledge about any specific GitHub organization or its practices encoded in code. They should always be passed through as settings.

Set up

Create a GitHub App for authentication

1. Create a GitHub App in your organization (not in your user) in Settings > Developer Settings > GitHub Apps (this is not the Settings > 3rd Party Access > GitHub Apps menu item). Leave all settings with their defaults except for:

   a. GitHub App Name: choose a globally unique name for this app, such as the [Name of org] PR Triage Bot

   b. Disable webhooks as we will not be using them.

   c. Permissions:

   • "Repository Permissions" -> "Metadata" -> "Read-only" (to get list of collaborators for a repo)
   • "Organization Permissions" -> "Members" -> "Read-only" (to get members of collaborating teams)
   • "Organization Permissions" -> "Projects" -> "Read and write" (to manage the GitHub project)

   d. Where can this GitHub App be installed? Set to Only on this account

2. After creating the app, you are on the app settings page:

   1. Create a private key, which should download it as a file.
   2. Note the "App ID". We will be using this to authenticate.
   3. Install the app in your organization (having access to all repos) using the Install App sidebar item.

3. Find the numerical app installation id for your organization. You can find this by looking at the last number in the URL for the installation settings - it would look like https://github.com/organizations/<organization>/settings/installations/<gh-app-installation-id>

Create the Project Board

This process is currently manual and finnicky, but is documented here so that we don't let the perfect be the enemy of the good.

So for now, go to the JupyterHub project board and "Make a copy" in your organization.

Note the project id in the url of your copy, which will look something like: https://github.com/orgs/<organization>/projects/<project-id>/views/1

Run as a local script

Clone this repository and do the setup above. You can then run the script manually with:

npm install
npm run build
node dist/src/main.js \
  --gh-app-id <github-app-id> \
  --gh-app-installation-id <github-installation-id> \
  --gh-app-pem-file <path-to-private-key> \
  [--repositories <repo1,repo2,repo3>] \
  <github-org-name> <github-project-id>

where:

1. <github-app-id> is the numerical app id for the app you created
2. <github-installation-id> is the installation id after you installed the app in your organization
3. <path-to-private-key> is the path to the private key you downloaded for your github app
4. <repo1,repo2,repo3> (optional) is a comma-separated list of repository names to limit querying to specific repositories instead of all repositories in the organization
5. <github-org-name> is the name of your github org
6. <github-project-id> is the numerical id of the project you copied

This should run for a bit and get you your project output!

Additionally, if you give the --dry-run option, no changes will actually be made to the project board. This may be useful when debugging issues with the script.

Using as a GitHub Action

This repository now provides a GitHub Action that can be used in workflows. To use this action:

1. Create an org-level secret using Org Settings > Secrets and variables > Actions with the contents of your app private key .pem file that was downloaded in the setup. We call this secret GH_APP_PRIVATE_KEY in our workflow below.

2. Create a workflow file like the following to run the bot every hour and to be able to manually trigger a run. If you are consolidating PR information from multiple repos, consider creating the workflow in a centralized repo like the organization's .github repo.

name: 'Update PR Triage Board'

on:
  schedule:
    - cron: '0 * * * *'  # Run every hour
  workflow_dispatch:

jobs:
  pr-triage:
    runs-on: ubuntu-latest
    steps:
      - name: Update PR Triage Board
        uses: yuvipanda/pr-triage-board-bot@main
        with:
          organization: 'your-org-name'
          project-number: '1'
          gh-app-id: '12345'
          gh-app-installation-id: '67890'
          gh-app-private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
          repositories: 'repo1,repo2'  # Optional: limit to specific repos. Delete this line to default to all repos in the org

Action Inputs

Input	Description	Required	Default
organization	GitHub organization name	Yes
project-number	GitHub Project board number	Yes
gh-app-id	GitHub App ID for authentication	Yes
gh-app-installation-id	GitHub App Installation ID	Yes
gh-app-private-key	GitHub App private key (PEM format)	Yes
repositories	Comma-separated list of repository names to limit querying (optional). If this is not specified, all repositories in the org will be queried.	No
node-version	Node.js version to use	No	23.x

Setting up the GitHub App

Follow the same GitHub App setup process described above in the "Create a GitHub App for authentication" section.

Acknowledgement

Thanks to 2i2c.org for initially building this, and donating it to the Jupyter organization!