Using GitHub Pull Requests with a Screen Reader

Guide Topics

 Skip to content

GitHub Pull Requests enable collaborative development by allowing contributors to propose changes to a repository. These changes are proposed in a branch and can be reviewed, discussed, and merged into the main codebase. This guide provides step-by-step instructions for screen reader users on how to navigate and interact with GitHub Pull Requests efficiently.

Note: This guide provides instructions specific to NVDA on a Windows desktop. Commands and shortcuts may vary for macOS, Linux, or other screen readers.

Prerequisites

  • A GitHub account for managing pull requests (PR)
  • Screen reader software installed (e.g., NVDA)
  • Basic familiarity with Git and GitHub repositories
  • ‘New Files Changed Experience’ feature preview is enabled

Setup

Screen Reader Modes

Screen readers on Windows generally work in two modes. Although screen readers generally switch to the correct mode automatically, sometimes you have to do it manually:

NVDA: Toggle between “browse” and “focus” modes with NVDA + space. “Focus” mode is indicated by a higher-pitched sound by default, whereas “browse” mode is indicated by a lower-pitched sound.

Note: The NVDA key is usually the Insert or Caps Lock, depending on your settings.

Tips

  • It is generally recommended to use “browse” mode when navigating pull requests, unless otherwise instructed.
  • Switch to focus mode (NVDA + space) before typing in textareas or inputs, then switch back to browse mode when you want to move around the page using quick navigation keys.
  • Use NVDA + F7 frequently to get an overview of headings, links, form fields, and buttons on the page; this is often faster than tabbing through many elements.
  • If your screen does not match the instructions or expected layout, ensure your browser window is maximized. Maximizing the window helps display all interface elements in their standard positions, which is important for screen reader navigation and following these steps accurately.

Enabling Feature Preview

From your account, you can view a list of features currently in public preview, each accompanied by a brief description. The New Files Changed Experience feature is included in this list and must be enabled to use:

Open the User Navigation Menu

  • Sign into your account.
  • If using “browse” mode, navigate to the “Navigation Menu” heading (H or Shift + H), or use D to navigate to the “Repository” navigation section.
  • Navigate to and select the “Open user navigation menu”.

Open Feature Preview

  • Navigate to the “Feature preview” option in the list and select it.

Enable the “New Files Changed Experience” Public Preview

  • Find the “New Files Changed Experience” in the feature list and select it.
  • Use Tab to navigate to the “Enable” or “Disable” button at the end of the feature list. This section also contains details about the feature and an option to provide feedback.
  • Confirm that the feature is enabled for your account.

Pull Requests List

Once you navigate to a repository’s pull requests page, you can access all the pull requests for that repo.

Locating the Pull Requests

  • Toggle to “browse” mode, if not already in this mode (NVDA + space).
  • Navigate to the “Pull requests list” heading level 2 (2 or H).
  • Navigate through pull requests (Tab or Shift + Tab).
    • The pull requests list has no per-item semantics, so screen reader users must infer which text is a title, author, or control and cannot jump directly from one PR to the next.
    • Hovercards announce their hotkeys, increasing verbosity and slowing navigation when scanning links. You can disable hovercards for previewing link content.

Load More Pull Requests

  • Navigate to the “Pagination” navigation section (D).
  • Navigate through the options (Tab).
  • Select an option to load another set of pull requests.

Open a Pull Request

  • Open the currently focused pull request by activating the pull request name (Enter)
    • Optionally, open pull request in a new tab (Ctrl + Enter).

Defining Search Criteria

You can narrow down the pull requests list by using the search functionality and filters.

Define Search Criteria

  • Navigate between form fields (E or Shift + E) until you reach the “search all issues” field.
  • Type keywords like “author”, “assignee”, “label”, “milestone”, or “status” to filter the list.
  • Enter a specific value for each filter to narrow the search results, for example “status:pending”.
  • Once you have added all the desired search parameters, press Enter to update the list of pull requests that match your search criteria.
  • Navigate to the results (2 or H).

Applying Filters

The actions toolbar provides various options for filtering, sorting, and managing pull requests.

Note: The filter buttons do not indicate the current filter state. To view the active filter conditions, refer to the pull request search box.

Focus on the Toolbar

  • Press Tab from the “search all issues” field until you reach the “Author” button, or
  • Press Shift + Tab from pull requests list until you reach the “Author” button

Select an Option

  • Navigate between different filtering options (Tab and Shift + Tab).
  • Once you have focused on the desired option, press Enter to activate it. This could open a dropdown menu or apply a filter.
  • If an option opens a dropdown menu, type or move through the menu items (↑ and ↓).
  • Select an item from the dropdown (Enter).

Apply Filters

  • Some options may apply filters immediately upon selection. For other dropdown options, you may need to press Esc after making your selections to apply them.

Creating Pull Requests

You can create a new pull request to propose changes to a repository. Pull requests enable collaboration by allowing maintainers to review, discuss, and merge changes.

Comparing changes

Once you navigate to a repository’s pull requests page:

  • Navigate to the “Search all issues” field.
  • Navigate to the “New pull request” link (K or Tab).
  • Activate the link which will lead you to the “Compare Changes” page

Selecting Branches

Branches in GitHub are parallel versions of a repo that allow you to work on different features, fixes, or experiments independently. This enables collaborative development and version control without affecting the main codebase until changes are merged.

  1. Use the “base” dropdown menu to select the branch you’d like to merge your changes into:
    • Navigate to the first heading level 1 (1 or Shift + 1)
    • Navigate to the “base” button (B). Note that this button is labeled with the currently selected branch.
    • Activate the button (Enter or space) to open a flyout menu and focus to a search field.
    • Optionally, use this search field to filter branch names by typing the desired branch name.
    • Navigate to the list of filtered results (Tab).
    • Navigate through the options (↑ and ↓).
    • Select and switch to the desired branch (Enter).
    • To return to the search field from the list of results, navigate back to the tabs control. Once there, use ← or → keys to move between the tab options, then press Shift + Tab to navigate to the search field.
  2. Use the “compare” drop-down menu to choose the topic branch you made your changes in:
    • Use previous steps to navigate the dropdown menu.

Once the base and compare branches are selected, you can review the commits and files changed.

  1. If a pull request contains many commits, they may appear in a separate “Commits” tab (separate from “Files changed”). Switch between them by activating the “Commits” or “Files changed” links.
  2. Commits are grouped by date under heading level 3, with each commit listed beneath its date.
    • Navigate to each date heading (3 or H).
    • Navigate through commits listed under a heading (I).
  3. To review the code differences, open the “Files changed” tab or link.
  4. Confirm the compare view shows the expected commits and file changes.
    • Navigate between links for each changed file (K).
    • Collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or space) to reveal the hidden lines. - Navigate through the code diffs (Ctrl + ALT + ↑ and Ctrl + ALT + ↓).

Start Pull Request

Open Pull Request

Configure Pull Request Details

  • Make sure the right branches are selected.
  • Switch to focus mode for reliable text entry (NVDA + space).
  • Navigate to the “Add a title” field (Tab repeatedly).
  • Type a descriptive title.
  • Navigate to the “comment” field (Tab).
  • Optionally, you can ask Copilot to generate text for the PR description from the toolbar.
    • Navigate to the “Copilot actions” button (Tab).
    • Activate to open a menu with options to generate a summary of changes or outline list of most important changes in this PR.
    • You can also edit the “Text Complete” setting if you have the “preview” enabled.
  • Type a descriptive comment.
  • To preview your description, navigate to the “Preview” tab (Shift + Tab) and press activate it (Enter).
  • When finished, return to browse mode with NVDA + space.
  • Enter additional information such as “Reviewers”, “Projects”, “Milestones”, “Development” by navigating to the corresponding menu buttons (B or Tab).

Create Pull Request

To submit a pull request that is ready for review:

  • Navigate to the “Create pull request” button (B or Tab).
  • From inside a text area you can also submit the form with (Ctrl + Enter).
Converting Pull Request to Draft

If your changes are not ready for formal review, you can convert it to a draft:

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the “Assignees” section (D).
  • Navigate to the “Convert to draft” button (Shift + B).
  • Activate the button to change the pull request status to draft.

Create Draft Pull Request

Draft pull requests are a way to propose changes that are still in progress and not yet ready for review or merging.

To create a draft pull request:

  • Follow the Comparing changes instructions
  • Find the “Select a type of pull request” menu (B or Tab).
  • Open it (Enter), choose “Create Draft Pull Request” with the arrow keys.
  • Activate the draft action button (Enter).
Converting Draft to Ready for Review

When your changes are complete and ready for formal review:

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the “draft state” section (D).
  • Navigate to the “Ready for review” button (B or Tab).
  • Activate the button to change the pull request status from draft to ready.
  • This will notify any assigned reviewers and allow the pull request to be merged once approved.

Reviewing Pull Requests

Pull request reviews allow collaborators to comment on proposed changes, approve them, or request further modifications before merging.

To open the desired pull request (refer to Pull Requests List for instructions). From here, you can review different pull request sections (e.g., Conversation, Commits, Checks Files changed).

Conversations

The Conversation tab is the main hub for discussing changes, viewing comments, and tracking the progress of your pull request. This tab lets collaborators discuss proposed changes, review feedback, and make updates before merging.

  • Navigate through the conversation threads by commenter (3 or H).
  • Navigate through the items (↑ and ↓).

Resolve Conversations

  • Navigate to a conversation thread.
  • If you have appropriate permissions, select “Resolve conversation” button to mark outstanding conversations as complete.
    • This will be at the end of the conversation thread.
  • Resolved conversations will be collapsed and marked as resolved.

Switching Tabs

The Conversation tab and the Checks tab use links inside the “Pull request tabs” section.

Once you are done reviewing the conversation, navigate to another tab (e.g., Commits, Checks, Files Changed):

  • Navigate to the “Pull request tabs” section (D).
  • Navigate between links (K or Tab).

  • Activate desired page.

    Commits

    The Commits tab displays all commits included in the pull request, organized chronologically by date. Each commit shows its author, timestamp, commit message, and a unique identifier (SHA). This tab helps reviewers understand the development history and progression of changes. You can select any individual commit to see its specific changes, review the code differences introduced in that particular commit, and understand the step-by-step evolution of the pull request.

  • Commits are grouped by date under heading level 3, with each commit listed beneath its date.
    • Navigate to each date heading (3 or H).
  • Navigate to each commit, which are heading level 4s (4 or H).
  • Navigate through each commit interactive element (Tab).
  • You can also navigate commits as list items (L or I), but this produces more verbose announcements.

Exploring Commits

Note that this will lead to a different commit page experience.

  • Navigate to desired commit heading level 4 (4 or H).
  • Press Enter to activate it and open the commit diff in a new page.
  • Navigate between links for each changed file (K).
    • Collapsed sections contain unchanged code. Focus the expand/disclosure control and activate it (Enter or space) to reveal the hidden lines.
  • Navigate through the code diffs (Ctrl + ALT + ↑ and Ctrl + ALT + ↓).
  • This individual commit page uses links inside the “Pull request tabs” section. To navigate to another tab:
    • Navigate to the “Pull request tabs” section (D).
    • Navigate between links (K or Tab).
    • Activate desired page.

Switching Tabs

The Commits tab and the Files Changed tab use a tab control inside the “Pull request navigation tabs” section.

Once you are done reviewing the commits, navigate to another tab (e.g., Conversation, Checks, Files Changed)

  • Navigate to the “Pull request navigation tabs” section (D).
  • Tab into the tab controls and use arrow keys to navigate between them (← or →).

  • Activate desired page.

    Checks

    The Checks tab shows the status of automated tests, continuous integration workflows, and other verification processes running on your pull request. This tab helps you verify if your changes pass all required tests and meet the repository’s quality standards before merging.

  • Navigate to the “check suites” section (D).
    • This will also move focus to the collapsed details button of the first check.
  • Navigate to each collapsed check button (B or Tab); each button is labeled with the check’s name.
  • Expand to reveal logs and other information for the check (Enter or Space):
    • Navigate through the check steps (K or Tab).
    • Activate for more details.

Review Checks Summary

  • Navigate to the “check run summary” section (D).
  • Review details about each check in this section.

Switching Tabs

The Conversation tab and the Checks tab use links inside the “Pull request tabs” section.

Once you are done reviewing the checks, navigate to another tab (e.g., Conversation, Commits, Files Changed):

  • Navigate to the “Pull request tabs” section (D).
  • Navigate between links (K or Tab).

  • Activate desired page.

    Files Changed

    The Files Changed tab displays a detailed comparison (diff) of all modified files between the base branch and the changes proposed in the pull request. This tab is essential for code review, showing additions and deletions line by line. Reviewers can comment on specific lines, suggest changes directly in the code, start review threads, and mark files as viewed once reviewed.

  • Navigate to the first heading level 1 (1 or Shift + 1).
  • Navigate to the “Pull request navigation tabs” section (D)
  • Navigate to the “Files changed” link (K or Tab) and activate it.
  • Use the new Files Changed experience while reviewing, ensure the “New Files Changed Experience” feature preview is enabled for your account.
    • Refer to the Enabling Feature Preview for steps to enable it. If it is not enabled, the legacy Files Changed UI will be shown.

Locating Specific Files (if needed)

If the pull request has many files, use the file filter to locate specific files.

  • Navigate the file tree:
    • Navigate to “file tree” heading level 2 (2).
    • Navigate through the available files (↑ and ↓).
    • Select file to navigate to file diff table.
  • Optionally, search for a specific file:
    • Navigate to the “Filter changed files” field (E or Shift + E).
    • Type the filename or path.
  • Optionally, use the filter options:
    • Navigate to “file tree” heading level 2 (2).
    • Navigate to the “Filter options” button (Shift + B).
    • Activate the button (Enter or Space).
    • Navigate through options (↑ and ↓) to find filters such as file extensions, viewed status, and code ownership.
    • Select an option (Enter or Space)
    • Repeat these steps to apply multiple filter options.
  • Navigate through the file headings (H or 3).
  • Switch between focus and browse modes as needed to type or explore content (NVDA + space).
  • Focus mode: navigate diff file tables:
    • Use arrow keys to navigate between the various table cells and review changes in each file.
    • Press Tab to locate the “More actions” button for additional options.
  • Browse mode: Examine line content in more detail.

Switching Tabs

The Files Changed tab and the Commits tab use a tab control inside the “Pull request navigation tabs” section.

Once you are done reviewing the changes, navigate to another tab (e.g., Conversation, Commits, Checks)

  • Navigate to the “Pull request navigation tabs” section (D)
  • Tab into the tab controls and use arrow keys to navigate between them (← or →)

  • Activate desired page.

    Submitting a Review

Add Comments to Specific Lines

  • Refer to the Files Changed Tab instructions for guidance.
  • Navigate to changed files and review changes.
  • Switch to focus (NVDA + space)
  • Navigate to a specific line you want to comment on.
  • Activate comment mode while focused on comment (Enter).
  • Type your comment in the markdown textbox, your focus is automatically moved here.
  • Select “Comment” button for immediate posting or “Start a review” button to batch comments.
  • When finished, return to browse mode with NVDA + space.

Add Comments to Multiple Lines

  • Refer to the Files Changed Tab instructions for guidance.
  • Navigate to changed files and review changes.
  • Switch to focus (NVDA + space)
  • Navigate to the starting line of what you want to comment on.
  • Select a range of lines for a multiline comment (Shift + ↓).
  • Active comment mode while focused on comment (Enter).
  • Type your comment in the markdown textbox, your focus is automatically moved here.
  • Select “Comment” button for immediate posting or “Start a review” button to batch comments.
  • When finished, return to browse mode with NVDA + space.

After reviewing changes and adding comments:

  • Navigate to the first heading level 1 (1 or Shift + 1).
  • Navigate to the “Submit review” button (B or Tab).
  • Activate the button.

Add Review Summary (Optional)

  • In the “markdown value” textbox, type a summary comment describing your overall feedback.

Choose Review Type

  • Tab to the “Review Event” radio options
  • Use your arrow keys to select one of the review options:
    • Comment: Submit general feedback without explicitly approving or requesting changes.
    • Approve: Submit feedback and approve merging the changes.
    • Request changes: Submit feedback that must be addressed before the pull request can be merged.

Submit Review

  • Navigate to the “Submit review” button (B or Tab).
  • Activate the button.

Managing Pull Requests

The pull request detail page contains comprehensive information including the title, description, labels, reviewers, and conversation history.

To open the desired pull request (refer to Pull Requests List for instructions).

Updating Information

Edit Pull Request Details

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the first heading level 2 (2 or Shift + 2).
  • Navigate to “Show options” menu button (Shift + B).
  • Activate the button.
  • Navigate to the “Edit comment” option (↑ and ↓).
  • Switch to focus mode for reliable text entry (NVDA + space).
  • Type an updated PR description.
  • Optionally, you can ask Copilot to generate text for the PR description.
    • Navigate to the “Copilot actions” button (Tab).
    • Activate to open a menu with options to generate a summary of changes or outline list of most important changes in this PR.
    • You can also edit the “Text Complete” setting if you have the “preview” enabled.
  • To preview your description, navigate to the “Preview” tab (Shift + Tab) and press activate it (Enter).
  • When finished, return to browse mode with NVDA + space.
  • Navigate to the “Update comment” button (Tab or press B) in browse mode.
    • From inside a text area you can also submit the form (Ctrl + Enter).

Add Comments

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the “Add a comment” section (D).
  • Navigate to the comment textbox (E).
  • Switch to focus mode for reliable text entry (NVDA + space).
  • Type your comment in the text area.
  • Navigate to the “Comment” button using Tab.
    • From inside a text area you can also submit the form (Ctrl + Enter).
  • To preview your comment, press Shift + Tab until you reach the “Preview” tab and press Enter.
  • When finished, return to browse mode (NVDA + space).

Assignees

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the “Select assignees” form section menu (D).
  • Expand menu (Enter or Space).
  • Type or select assignees from the dropdown list.
  • Confirm the selection (Enter).
  • Close menu (Esc).

Follow the same steps to set values for Projects, Milestones and Development.

Labels

  • Navigate to the pull request’s Conversation tab.
  • Navigate to the “Select assignees” form section menu (D).
  • Navigate to “Labels” menu button (B or Tab).
  • Expand menu (Enter or Space).
  • Type or select labels from the dropdown list.
  • Confirm the selection (Enter).
  • Close menu (Esc).

Requesting Reviews

  • Navigate to the “Select reviewers” form section menu (D).
  • Expand menu (Enter or Space).
  • Type or select reviewers from the dropdown list.
  • Confirm the selection (Enter).

Closing or Merging

Closing a Pull Request

  • Navigate to the first heading level 1 (1 or Shift + 1).
  • Navigate to the comment area.
    • Navigate to the “Add a comment” section (D).
  • Optionally, add a comment explaining why you’re closing the pull request.
  • Navigate to the “Close pull request” button (Tab or press B) and activate it.

Merging a Pull Request

  • Ensure all required reviews and status checks are complete.
  • Navigate to the “Conflicts” section (D).
  • Address any conflicts listed here.
  • Optionally, you can navigate to the “Select merge method” button (B or Tab) to choose a merge option:
    • Create a merge commit: All commits from this branch will be added to the base branch via a merge commit.
    • Squash and merge: The commits from this branch will be added to the base branch.
    • Rebase and merge: The commits from this branch will be rebased and added to the base branch.
  • Navigate to the “Merge pull request” button (B or Tab).
  • Switch to focus mode for reliable text entry: press NVDA + space.
  • Type a descriptive title in the “Commit message” textbox.
  • Navigate to the “Extended description” textbox and type a descriptive message of what is included in the PR.
  • Select the “Confirm merge” button (B or Tab) to complete the merge.
  • Optionally, delete the feature branch after merging.
    • Navigate to the “Add a comment” section (D).
    • Navigate to the “Delete branch” button (Shift + B).
    • Activate the button.

Resources

Please share questions or comments on the accessibility community discussion page.

Accessibility Documentation