Using GitHub Repositories with a Screen Reader

Guide Topics

 Skip to content

GitHub repositories are essential for collaborating on code, tracking issues, and managing projects. This guide provides step-by-step instructions for screen reader users on how to navigate and interact with GitHub repositories 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

  • Sign up for a GitHub account
  • Screen reader software installed (e.g., NVDA)

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.

It is generally recommended to use “browse” mode when navigating repositories, unless otherwise instructed.

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

Open a Repository

To explore a GitHub repository (repo), follow these steps once you sign in to your GitHub account:

  • Toggle to “browse” mode, if not already in this mode (NVDA + space).
  • Navigate to the Search Bar (F)
  • Press space key to type in the search bar to look for a repo.
    • If your account has repos available, you can navigate to them using the ↑ and ↓ keys.
  • Once you search, the focus will be placed in a heading level 2 with the total number of results.
  • To sort the results, navigate to the “Sort by” menu button using Tab. Activate the menu (Enter or space) and use the ← and → keys to cycle through the sorting options. Press Enter or space to select an option and apply the sorting.
  • Press H to move to the next repo heading, skipping other content and focusing on repo titles, or press 3 as repo titles are marked with heading level 3.
    • You can use the ↑ and ↓ keys to read and navigate through the repo details.
  • Press Enter to open a repo.

Repository Structure

Repository Tabs

The “Repository Navigation” landmark includes the following tabs:

  • Code: This tab serves as the starting point of a repo. It provides access to the repo’s README file, allows interaction with its files, and offers options for downloading, cloning, or forking the repo.
  • Issues: Displays a list of open and closed issues which help track and manage bug reports, feature requests, questions, or tasks related to the project. Issues can be assigned to collaborators and linked to pull requests or other GitHub features for seamless project management.
  • Pull Requests: Shows all pull requests for the repo and it facilitates collaboration by allowing contributors to propose changes to the repo. Pull requests enable maintainers to review, discuss, and merge changes into the codebase or request further modifications.
  • Discussions (if enabled): A space for open-ended conversations that don’t fit into issues or pull requests. Discussions serve as a forum for brainstorming, sharing ideas, or addressing broader topics related to the project.
  • Actions: Automate workflows and tasks within the repo using GitHub Actions. This tab provides tools to set up continuous integration, deployment pipelines, and other automated processes.
  • Projects (if enabled): Organize and track work using project boards. This tab helps visualize tasks, assign responsibilities, and monitor progress across the team.
  • Wiki (if enabled): Create and maintain detailed project documentation. The wiki is ideal for instructions, guides, and other resources specific to the repo.
  • Security (if enabled and with appropriate permissions): Monitor and manage the repo’s security settings. This tab includes tools for vulnerability scanning, dependency analysis, and other security-related features.
  • Insights (with appropriate permissions): Access analytics and metrics about the repo, such as contributor activity, commit history, and code frequency, through visual graphs and charts.
  • Settings (with appropriate permissions): Configure repo-specific options, including access permissions, branch protection rules, and administrative actions like deleting the repo.

Repository Key Sections

The repo main page is organized into the following landmark sections:

  • Repository Navigation: This section contains the main tabs of a repository.
  • Main: This area displays the primary content of the repo, including the file and folder list, branches, the “Code” button, repo details, contributors, deployments, and other key information.
  • Repository Files Navigation: This section showcases the contents of the repo’s README file, which typically provides detailed project information, installation instructions, and usage guidelines.

To navigate between these landmarks, press D. Within each landmark, navigate through the sections by pressing H or 2, as most subsections are organized under level 2 headings.

Once you open a repository, you can view, edit, and commit files.

Opening a File

  1. Press T to navigate to the files table. This table includes columns for name, last commit message and last commit date.
  2. Navigate between columns using Ctrl + Alt + ← and Ctrl + Alt + →.
  3. Navigate between rows using Ctrl + Alt + ↑ and Ctrl + Alt + ↓.
  4. Press Enter or space on a file or folder name to open it.

Note: If you open a folder, it will display a new table with the same navigation structure. Repeat these steps to locate and open the desired file.

Searching for a File

  1. Navigate to the “go to file” combobox by navigating to the first level 1 heading (1 or Shift + 1) and pressing F until the combobox is focused.
  2. This field will search the files of the current repo and suggest matching results. The screen reader will indicate the top result and autofocus it. You can navigate between results with the ↑ and ↓ keys.
  3. Press Enter to open the selected file.

Editing a File

  1. Open a file.
  2. Use K to navigate through links until the “Edit file” link is focused.
  3. Activate link (Enter) to enter the editing mode.
  4. Using “focus” mode is recommended for editing a file. Press NVDA + space keys to toggle to “focus” mode.
  5. Make your changes to the file.
  6. Press Esc key so you can move focus from the text area.
  7. Press Shift + Tab to navigate to the “Commit Changes” button.
  8. Activate the button to open “Commit Changes” dialog.
  9. Type a commit message and submit to commit changes.

Engaging with Repositories

GitHub provides several features to help you stay connected with repositories, including cloning, watching, forking, and starring. These tools enable you to track activity, contribute to projects, and bookmark repositories for quick access.

Cloning

To download the contents of a repo to work locally, you can clone it using Git. Once you open a repository:

  1. Navigate to the first heading at level 1 on the page. This heading contains the repo’s name and owner.
  2. Press B to navigate to the “Code” button.
  3. Activate the button (Enter or space) to open a flyout menu.
  4. Press Tab to navigate to your preferred remote URL option: HTTPS or SSH.
    • Alternatively, if you want to download the repo as a ZIP file, navigate to the “Download ZIP” option and activate it. Skip the remaining steps if you choose this option.
  5. Select the “Copy url to clipboard” button to copy the repo link.
  6. Open your command prompt or “Git Bash”. If git is not installed, follow the instructions to install Git on Windows.
  7. Change the current working directory to the location where you want the cloned directory.

  8. Type “git clone”, and then paste the URL you copied earlier:

     git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
  9. Press Enter to create your local clone.

Watching

Watching a repo keeps you informed about its activity. Once you open a repository:

  1. Use L to move through lists until you reach the “Main” landmark containing the “Watch” submenu.
  2. Open the submenu (Enter or space).
  3. Use the ↑ and ↓ keys to navigate through the available options.
  4. Select your preferred option to receive notifications about specific activities.
  5. If you choose the “Custom” option, a dialog will open:
    • Mark the checkboxes for the activities you want to be notified about.
    • Press the “Apply” button to save your preferences and close the dialog.

Forking

Forking a repo on GitHub allows you to create your own copy of someone else’s project, enabling you to experiment, make changes, and potentially contribute back to the original project. Once you open a repository:

  1. Use L to move through lists until you reach the “Main” landmark containing the “Watch” submenu.
  2. Press I to move through the list items until you locate the “Fork your own copy of (repo name)” link.
  3. Open the “Fork your own copy of (repo name)” link (Enter).
  4. Follow the instructions to select the destination for the Fork.
    • Use the Tab key to navigate through the options.
    • Press Enter to select your desired destination.
  5. GitHub will create a copy of the repo under your chosen account. Once completed, you’ll be redirected to your new forked repo.

Starring

Starring a repo allows you to bookmark it for quick access. Once you open a repository:

  1. Use L to move through lists until you reach the “Main” landmark containing the “Watch” submenu.
  2. Press I to move through list items until the “Star this repository” button is focused.
  3. Activate the “Star this repository” button (Enter or space).
    • To remove the star, navigate to the “Unstar this repository” button and activate it (Enter or space).

Branches and Tags

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

To switch branches:

  1. Navigate to the first level 1 heading (1 or Shift + 1)
  2. Press B to navigate to the “main branch menu” button. Note that this button is labeled with the currently selected branch.
  3. Activate the button (Enter or space) to open a flyout menu and focus to a search field.
  4. Use this search field to filter branch names by typing the desired branch name.
  5. Press Tab until you reach the list of filtered results.
  6. Navigate through the options using the Tab or arrow keys.
  7. Press Enter to select and switch to the desired branch.
  8. 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.

Switching Tags

Unlike branches, a tag is a reference that points to a specific commit in a repo’s history, commonly used to mark important milestones like release versions.

To switch to a tag:

  1. Navigate to the first level 1 heading (1 or Shift + 1)
  2. Press B to navigate to the “main branch menu” button. Note that this button is labeled with the currently selected branch.
  3. Activate the button (Enter or space) to open a flyout menu and focus to a search field.
  4. Use this search field to filter tag names by typing the desired tag name.
  5. Press Tab until you reach the tabs control with the branch and tag tabs.
  6. Use the ← or → keys to move to the “Tags” tab.
  7. Press Tab to reach the list of filtered results.
  8. Navigate through the options using the Tab or arrow keys.
  9. Press Enter to select and switch to the desired tag.
  10. To return to the search field from the list of results, navigate back to the tabs control. Once there, use ← and → keys to move between the tab options, then press Shift + Tab to navigate to the search field.

Resources

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

Accessibility Documentation