This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Repositories

Watch Repositories on GitHub for PRs

Repositories are the bucket by which PR Focus groups pull requests.

As a user of PR Focus, you can add one or more repositories that you want to watch. When you Fetch PRs, PR Focus makes API calls to GitHub to get open PRs for all of the repositories you’re watching, as well as updating existing PRs that PR Focus has previously ingested.

You can view pull requests in a specific repository, or view an All Repositories dashboard that aggregates all the PRs across all the repositories you’re watching.

You can customize the way PR Focus displays repository details, including:

  • Customizing the repository name or changing the repository label color that displays in the PR Summary view
  • Customizing the columns that display in the repository dashboard when you view a specific repository

You can also customize how often PR Focus fetches updates for the repository, or how long PR Focus waits before setting a pull request to “Inactive” or “Archived.”

You can delete a repository from PR Focus, which also deletes all pull requests for the repository.

1 - Add Repositories

Add repositories to watch for new and updated PRs.

You can add a repository to PR Focus using the Add Repositories option in the Repositories menu.

Screenshot showing the “Add Repositories” menu option

This opens a window where you can add one or many repositories.

Add One Repository

By default, when you open the Add Repositories window, you see the option to add a single repository.

Enter a GitHub URL for the repository you want to add, similar to https://github.com/dacharyc/prfocus-website.

You can also select a color for the repository pill to help visually distinguish the repository in a list.

Screenshot showing the “Add one” option in the “Add Repository” pane, with a text field to enter a URL, a picker to select a color and a save buttons

Press the Add Repository button to add the repo to the list of repositories you’re watching.

The repository appears in the sidebar. PR Focus enqueues a job to automatically fetch the open pull requests in the repository from GitHub. Once any running jobs are complete, PR Focus gets the open PRs for the new repository.

If you view Manage Repositories option in the Repositories menu, you’ll see the repository in your list of watched repositories. From here, you can click a link to view the repository in GitHub.

Screenshot showing the Manage Repositories window with links to view repositories on GitHub, and buttons to update settings or delete the repositories

Add Many Repositories

If you want to quickly onboard a team to PR Focus, you can create a list of repository URLs to add to the app.

When you open the Add Repositories window, you’ll see the option to Add many.

Screenshot showing the Add Repo sheet, with Add Many selected and a text box to enter many repository URLs

When you select this option, you can enter a list of repository URLs separated by newlines. PR Focus parses this list and adds all of the repositories to the app.

When adding many repositories, you cannot customize the color of the labels. PR Focus starts at the top of the color list and assigns a different color to each repository in the list. If you enter more repositories than colors, PR Focus starts assigning label colors again at the beginning of the list.

You can manually customize these labels later if you configure repository settings.

What’s Next

2 - View a Repository

View the Repository Dashboard to see only PRs for that repository or change repo settings.

When you select a repository in the sidebar, this opens the Repository Dashboard. From here, you can:

  • Manage incoming PRs
  • View any PR in GitHub
  • View the details of a specific PR in PR Focus
  • Manage details about the repository, or stop watching it

Or if you want to view a rollup of all the PRs you’re watching in one view, you can select the All Repositories view, which displays all the pull requests from the individual repository dashboards in an aggregate view.

The Repository Dashboard

The Repository Dashboard breaks down into different lists of pull requests. By default, you see:

  • Inbox: a list of Incoming PRs
  • Watched PRs: a list of PRs you’ve chosen to watch
  • My PRs: a list of your PRs in the repository
  • Reviewing PRs: a list of PRs where you’re a reviewer

Optionally, if your workflow involves assigning PRs, you can check the setting in the Settings or in the repository’s Update Settings to Show Assigned PRs. This adds a fifth list of PRs that are assigned to you.

Screenshot showing the Repository Dashboard

PR Summary

A summary view gives you information about each PR in the repository, including:

  • The PR’s title
  • The PR number
  • The repository where the PR exists
  • Whether a PR has merge conflicts
  • Whether a PR is open, closed, or merged
  • Whether there are any checks for the PR, and if those checks have passed or failed
  • The number of commits in the PR
  • The number of comments on the PR
  • The number of reviews the PR has gotten

You can click into a PR summary to see the full details of the pull request.

The background color of the PR summary changes when the PR has new updates since you last viewed the details. PR Focus uses your macOS settings for Light or Dark mode.

In Light mode, a PR summary with a bright white background has updates you haven’t seen. One that is gray does not have any new updates since you last viewed it.

Screenshot of a PR Summary with new updates in Light mode - the background is bright white

In Dark mode, a PR summary with a gray background has updates you haven’t seen. One that is dark black does not have any new updaets since you last viewed it.

Screenshot of a PR Summary with new updates in Dark mode - the background is gray instead of dark black

PR Summary Context Menu

You can right-click on a PR summary to open a context menu. This menu lets you quickly perform common actions without clicking into the pull request details.

The available options change depending on the context in which you open the menu. For example, if a PR is closed or merged, one of the options in the context menu is “Archive PR.” If the pull request is open, this option is not available.

You can always select “Open in GitHub” to immediately interact with the PR on GitHub. Or you can click into the pull request details to view the details without leaving PR Focus.

Screenshot showing the PR Summary context menu, with options to watch or ignore a PR, or open it in GitHub

Conflicts

A PR’s “Conflicts” icon can indicate one of three states:

  • A green check: A PR has no merge conflicts.
  • A gray check: GitHub hasn’t finished calculating whether a PR has merge conflicts.
  • A red X: A PR has merge conflicts.

Status

A PR’s “Status” can be one of four states:

  • Open: Indicated by a green pull request icon: A green git PR open icon
  • Draft: Indicated by a grey pull request draft icon: A green git PR open icon
  • Merged: Indicated by a purple merged icon: A purple git merged icon
  • Closed without merging: Indicated by a red pull request closed icon: A red git PR closed without merging icon

Checks

A PR’s “Checks” include jobs that run on a PR before merging, such as linters, test suites, or other CI jobs. The status of these jobs is indicated as one of three states in the PR summary:

  • A green check: A PR has at least one check, and it has passed all checks.
  • A red X: A PR has at least one check, and it has failed at least one check.
  • An “N/A”: A PR has no checks, or the status of checks is unknown.

When you click into a PR’s details, you can see the status of individual checks.

Inbox

When a new PR is opened in a repository you’re watching, PR Focus checks for a few things:

  • Are you the PR author? If so, the PR goes to My PRs.
  • Are you an assignee? If so, the PR goes to Assigned PRs
  • Are you a reviewer or requested reiewer? If so, the PR goes to Reviewing PRs

If none of those things applies, the pull request appears in the Inbox. From here, you can view the PR’s details and decide whether to Watch or Ignore a PR. If the PR is closed, you can Archive it. If you later become a reviewer or an assigned contributor, the PR moves to one of those columns whether or not you Watch or Ignore it.

The aggregate Inbox gives you the option to perform bulk operations. You can select multiple PRs and Watch or Ignore them. If you select multiple closed PRs, you can Archive them.

For more information about processing incoming PRs, refer to Incoming PRs.

Watched PRs

When you choose to Watch an incoming PR, it moves into the Watched PRs list for the repository and in the All Repositories rollup view.

You can stop watching a PR at any time by either:

  • Clicking into the PR Details and pressing the Stop Watching button.
  • Right-clicking on the PR Summary and selecting Stop Watching from the context menu.

If the PR is still open, it goes back to your Inbox. If the PR is no longer open, it disappears from all dashboards.

You can also choose to Ignore a pull request that you’re currently watching. If you select this option, PR Focus stops watching the PR and moves it to the Ignored PRs dashboard.

Choosing to Watch or Ignore a PR does not move a pull request out of the My PRs, Assigned PRs or Reviewing PRs columns.

My PRs

When the GitHub user who created the PR is the same as the GitHub user in the PR Focus Global Settings, the app considers you the PR author and automatically moves the PR into My PRs. PR Focus does not provide a way to manually designate a PR as “mine.”

Choosing to Watch or Ignore a PR does not move the pull request out of the My PRs column. The only way to move a pull request you’ve made is waiting for it to become inactive and move to the Inactive PRs dashboard, or waiting for it to close and move to the Archived PRs dashboard.

Reviewing PRs

When the GitHub user in the PR Focus Global Settings is the same as a GitHub user in the requestedReviewers array in the GitHub Pull Request API, PR Focus moves the PR into the Reviewing PRs list.

When you review a PR, GitHub automatically adds you to the requestedReviewers array. Someone else, such as the PR author, can also add you as a requestedReviewer by requesting a review from you.

If you do not use this workflow, you can hide the Reviewing PRs list from your dashboards by un-checking the Show Reviewing PRs checkbox in the Global Settings or Repository Settings.

Reviewing PRs is enabled by default.

Note: PR Focus does not have support for requestedTeams because it does not have information about teams. If your organization uses requested teams, PR Focus will not add the PR to your Reviewing PRs list until you actually review the PR. If this is a feature that is important to you, please file a feature request or leave a comment or an emoji reaction if this feature request already exists.

Assigned PRs

When the GitHub user in the PR Focus Global Settings is the same as a GitHub user in the assignee field or the assignees array in the GitHub Pull Request API, PR Focus moves the PR into the Assigned PRs list.

If you do not use this workflow, you can hide the Assigned PRs list from your dashboards by un-checking the Show Assigned PRs checkbox in the Global Settings or Repository Settings.

Assigned PRs is disabled by default.

Sort PRs in the Repository Dashboard

You can sort pull request lists in the repository dashboard by a number of options. By default, all lists in the repository dashboards are sorted by updated date. Recently updated PRs always appear at the top of the lists.

You can change the sort order of Watched PRs, Assigned PRs, Reviewing PRs, or My PRs with one of these sort options:

  • Review count: Sort in descending order by the number of reviews
  • Comment count: Sort in descending order by the number of comments
  • Commit count: Sort in descending order by the number of commits
  • State: Group PRs together by state; Closed, Open, or Merged
  • Broken: Show PRs with failing status checks and/or merge conflicts at the top of the list
  • Updated date: Sort in descending order by updated date
  • Closed date: Sort in descending order by closed date. Only closed PRs have a closed date.
  • Merged date: Sort in descending order by merged date. Only merged PRs have a merged date.

You can individually change the sort order for each column. PR Focus does not preserve the sort order you select and always defaults to showing PRs in descending order by updated date.

Screenshot showing the opened “Sort by” menu with the available sort options

PR Movement Between Lists and Dashboards

Pull requests may move automatically between lists and dashboards depending on things like whether you are a reviewer or assignee, or whether the PR has been inactive or closed for a period of time. You can manually change the status of PRs by watching or ignoring them, or by archiving a PR that is closed or merged.

Manually Move PRs Between Lists and Dashboards

When you Watch or Ignore a PR in your Inbox, the PR moves to the Watched PRs list or the Ignored PRs dashboard.

You can manually change the status of a watched or ignored PR at any point by either:

  • Clicking into the PR Details and pressing the appropriate button.
  • Right-clicking on a PR Summary and selecting the appropriate option from the context menu.

You can also right click on the PR Summary of a closed or merged PR and select the Archive PR option to immediately move it to the Archived PRs dashboard.

Automatic Movement Between Lists and Dashboards

PRs may also move between lists automatically in the Repository Dashboard and Inactive/Archived dashboards when:

  • You become a reviewer or an assignee on a pull request. When this occurs, the PR moves into one of those respective columns.
  • A PR has been inactive for longer than the Days until inactive setting. When this occurs, the PR moves into the Inactive PRs dashboard.
  • A PR has been closed or merged for longer than the Days until archive setting. When this occurs, the PR moves into the Archived PRs dashboard.

You can customize these settings on a per-repository basis, or by changing the Global Settings from their default values. For more information, refer to:

View PR Details

At any time, you can click into a PR Summary in a list or dashboard to view the PR details. When you are viewing the PR details, you can press the buttons to Watch or Ignore a PR. For more information, refer to View PR Details.

Fetch New and Updated PRs in the Repository

While PR Focus is open, it automatically fetches and updates PRs in the repositories. You can configure the interval at which PR Focus fetches and updates PRs in two ways:

The default interval for fetching and updating PRs is every hour.

If you configure repositories to fetch different intervals, you may see some repos not included in a “fetch PRs” job run in the logs. For example, you may have a few repositories fetching updates several times per hour, but the rest on an hourly cadence. When each of these jobs run, you’ll only see the repositories with that fetches interval appear in the logs for that job.

Manually Fetch PRs

When a job is running, you cannot manually fetch PRs. An animation appears in the PR Focus toolbar and replaces the Fetch PRs buttons. The buttons return when the job is complete.

Screenshot showing the animation in the toolbar that replaces the “Fetch PRs” button

Fetch all PRs

You can manually press the Fetch all PRs button at the upper right hand of the PR Focus window. This gets updates from GitHub for all of the repositories you watch.

Screenshot showing “Fetch PRs” button in the toolbar

Fetch PRs for a Specific Repository

You can manually press the Fetch specific repo button at the upper right hand of the PR Focus window. This opens a dropdown of all of the repositories you’re watching. You can select a specific repository, and PR Focus fetches only the updates for that repository. This is useful if you’re watching a lot of repositories, and don’t want to wait for all of the fetch jobs to run - you can quickly fetch only the updates for a single repository.

Screenshot showing “Fetch specific repo” button in the toolbar, with the SDK Docs repository highlighted

What Does Fetching PRs Do?

When you press the Fetch PRs button, this kicks off a few jobs:

  • It fetches a list of open pull requests in all of the repositories you’re watching
  • It fetches updates from the repository for “open” PRs that PR Focus knows about:
    • If the PR has previously been added and is still open in PR Focus but closed in the remote repository, PR Focus fetches updates from the remote repository, and updates the status.
    • If the PR is merged or closed in PR Focus and not listed as “open” on the remote repository, PR Focus does not fetch updates for it.
    • While fetching updates, PR Focus looks for any new commits, comments, reviews, or status checks, adds them to the PR details, and increments the PR summary counts.
    • If PR updates include adding you as an assignee or requestedReviewer, PR Focus moves the PR to the appropriate list in your dashboard.

3 - Repository Settings

Update repository metadata in PR Focus, or stop watching the repository.

To update the settings for repositories you’re watching, or to delete repositories from PR Focus, select the Manage Repositories option in the Repositories menu.

Screenshot showing the Manage Repositories menu option

When you select this option, you open the Manage Repositories window. This window provides:

  • A list of all the repositories you’re watching
  • Links to navigate directly to the repositories in GitHub
  • Buttons to update the settings for each repository
  • Buttons to delete repositories from PR Focus

Screenshot showing the Manage Repositories window with links to view repositories on GitHub, and buttons to update settings or delete the repositories

When you press the Update Settings option, you open the repository settings window for that repository.

Screenshot showing the “Repository Details” view with metadata and customization options

Repository Metadata

Above the divider, you see Repository Details. These pieces of metadata are derived from the URL you provide when you Add a Repository.

The GitHub URL contains the owner and repository name, which PR Focus extracts to the relevant pieces of metadata. If you ever forget what a repository is, or need a quick way to get to the repository, you can click the Repository URL to go to the repository in a web browser.

The repository name from this URL is displayed as the Repo Name in the PR Focus sidebar, and on the repository label in the PR Summary.

Customize Repository Appearance

You can customize these repository details:

  • Provide a custom, human-friendly name for the repository, which replaces the default Repo Name in the PR Focus sidebar and on the repository label in the PR Summary
  • Select a repository label color to make it easier to distinguish the repository that a PR belongs to when viewing the All Repositories dashboard

In the example below, the realm-kotlin repository name has been replaced by the custom Realm Kotlin name, and a specific color has been chosen for the repository label.

Screenshot showing a PR Summary

You can customize the repository appearance independent of customizing repository settings. Pressing the Update Apperance button only changes the repository’s custom name and label color; it does not affect the repository settings below the divider.

Customize Repository Settings

In this view, you can also customize the settings for a repository. Settings you customize here override the Global Default settings for these options. The settings you can customize include:

  • Which columns to show in the repo dashboard.
    • If you’ll never be a reviewer, assignee, or contributor to the repository, you can select the “Watch-only view” setting. This removes the My PRs, Reviewing PRs, and Assigned PRs columns when viewing that repository. When you toggle this setting, the rest of the options disappear.
    • If you may be a reviewer, assignee, or contributor to the repository, you can check which columns apply to your role in that repository. PR Focus shows the corresponding columns in the Repository Dashboard, and in the All Repositories dashboard.
  • How many days to wait before setting a PR to “inactive.” When a PR becomes inactive, it moves out of the repository dashboards to the Inactive PRs dashboard. This helps avoid cluttering your repository dashboards with pull requests that may be blocked.
  • How many days to wait after a PR has been closed before setting it to “archived.” When a PR has been closed or merged for the designated number of days, it moves to the Archived PRs dashboard.
  • How often to fetch PRs for the repository. For some repositories, you may only need to see updates daily, and more frequent updates would be a distraction. For other repositories, you may want to see updates whenever you look at PR Focus, so you may want it to update as often as several times per hour. The default fetch interval is one hour.

When you press the Save Repo Settings button, PR Focus saves all of the values in the “Customize Repository Settings” section of the view as custom repository settings. These settings apply only to this repository, and override the global default settings for this repo.

If you would instead like to customize the global default settings, refer to Settings

GitHub Fetch Frequency

The GitHub API rate-limits API access tokens to 5,000 calls per hour.

PR Focus makes a call to fetch the list of open PRs in a repository, and then makes indvidiual calls to get the details of each pull request it needs to update.

If you are watching many repositories, or if the repositories you watch have many open PRs, the fetch job can be quite lengthy and can consume hundreds of API calls per run. For this reason, we recommend not fetching PR updates too often. The default fetch interval is hourly. The most frequent fetch interval that PR Focus provides for its automated jobs is “several times per hour.” You can manually fetch updates at any time by pressing the Fetch PRs button, but if the rate limit has been exceeded, you won’t see any updates to your pull requests in PR Focus.

Note: Currently, PR Focus has minimal handling for exceeding the rate limit. If you don’t see updates to PRs you expect, check the PR Focus Logs to see if there are any error messages related to exceeding the rate limit. You may want to stagger the fetch interval across repositories if you encounter issues with the GitHub rate limit.

4 - Delete a Repository

Delete a repository and all of its PRs from PR Focus.

You can delete a repository from PR Focus the Manage Repositories option in the Repositories menu.

Screenshot showing the Manage Repositories menu option

This opens the Manage Repositories window.

Find the row for the repository you want to delete, and press the Delete repo button. This deletes the repository and all of its pull requests from PR Focus.

Screenshot showing the Manage Repositories window with an arrow pointing to the circled “Delete Repo” button for the ‘dacharyc/GitHubGraphQLAPITester’ repo.