# Pre-Workshop Setup - GIT Going with GitHub > > **Listen to Episode 1:** [Pre-Workshop Setup](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned. ## Everything You Need Before Day 1 Begins > **A [Community Access](https://community-access.org) workshop.** > > **Please complete this guide at least one day before the workshop.** If you run into any issues, [file an issue](https://github.com/community-access/git-going-with-github/issues) so we can help - we want Day 1 to start with everyone ready to go, not troubleshooting. ## Table of Contents 1. [What You Will Need](#what-you-will-need) 2. [Step 1 - Create Your GitHub Account](#step-1---create-your-github-account) 3. [Step 2 - Configure GitHub Accessibility Settings](#step-2---configure-github-accessibility-settings) 4. [Step 3 - Configure Your Profile](#step-3---configure-your-profile) 5. [Step 4 - Check GitHub Feature Preview Settings](#step-4---check-github-feature-preview-settings) 6. [Step 5 - Set Up Your Screen Reader and Browser](#step-5---set-up-your-screen-reader--browser) 7. [Step 6 - Install Git and Visual Studio Code](#step-6---install-git-and-visual-studio-code) 8. [Step 7 - Configure Git Identity](#step-7---configure-git-identity) 9. [Step 8 - Install VS Code Extensions](#step-8---install-vs-code-extensions) 10. [Step 9 - Verification Checklist](#step-9---verification-checklist) 11. [Other GitHub Access Methods (Reference Only)](#other-github-access-methods-reference-only) 12. [Getting Help Before the Event](#getting-help-before-the-event) ## What You Will Need ### Hardware - A computer running Windows or macOS - A reliable internet connection - Headphones (recommended - screen reader audio during group sessions) ### Software - Day 1 - A modern web browser: **Chrome** or **Firefox** recommended - Both have strong compatibility with GitHub's interface and screen readers - Edge is also acceptable on Windows - Safari is the recommended browser on macOS with VoiceOver - A screen reader (see options below) - A GitHub account (free tier is fine) ### Software - Required Before the Workshop - **Git** - [Download Git](https://git-scm.com/downloads) (Windows/Linux) or Xcode Command Line Tools (macOS) - **Visual Studio Code** (free) - [download here](https://code.visualstudio.com/) (GitHub Copilot is included automatically) - A GitHub Copilot subscription or Free tier access (Copilot Free is available to all GitHub users) ### Screen Reader Options You only need **one** of these. Use whichever you are most comfortable with. | Screen Reader | Platform | Cost | Download | | --------------- | ---------- | ------ | ---------- | | **NVDA** (NonVisual Desktop Access) | Windows | Free | [Download NVDA](https://www.nvaccess.org/download/) | | **JAWS** (Job Access With Speech) | Windows | Paid (trial available) | [Download JAWS](https://www.freedomscientific.com/products/software/jaws/) | | **VoiceOver** | macOS / iOS | Built-in (free) | Included with macOS - press `Cmd+F5` to activate | > **Note:** All workshop exercises are designed to work with any of these screen readers. Where specific key commands differ, we will note all three. You are not disadvantaged by using any particular screen reader. ## Step 1 - Create Your GitHub Account If you already have a GitHub account, skip to [Step 2](#step-2---configure-github-accessibility-settings). > **Before you begin:** Have your email address and a chosen password ready. The signup form is a single-page form with several fields - your screen reader will encounter a verification puzzle partway through (see note below). ### Create an account 1. Open your browser and navigate to the **[GitHub signup page](https://github.com/signup)** 2. The page loads with focus on the first field: **"Enter your email address"** - Type your email address and press `Tab` or activate **Continue** 3. The next field is **"Create a password"** - Choose a password of at least 8 characters (15+ recommended). Press `Tab` or **Continue** 4. The next field is **"Enter a username"** - Your username appears on every issue, PR, and comment you make. Guidelines: - Use lowercase letters, numbers, and hyphens only - Keep it professional - it represents you in the open source community - GitHub will tell you immediately if the name is taken - Press `Tab` or **Continue** 5. The next question asks whether you want to receive product updates by email - Press `Tab` to reach the **"y"** or **"n"** options and press `Enter`, or type `y` or `n` directly 6. **Human verification step**
Visual / mouse users GitHub presents a visual CAPTCHA puzzle to verify you are human. Follow the on-screen prompts - typically clicking images that match a category, or checking a box. If the puzzle does not load, try refreshing the page.
Screen reader users GitHub's visual CAPTCHA is a known accessibility barrier. After the CAPTCHA appears: - Look for a button or link labeled **"Audio"** or **"Try an audio challenge"** - an audio CAPTCHA alternative may be available - If no audio option appears, or if neither challenge is accessible, contact the workshop organizer before the event - they can assist with account verification - If you complete an audio challenge, you will hear words or digits to type into a text field
7. Activate the **Create account** button 8. GitHub sends a **launch code** (a short numeric code) to your email inbox - Check your email, copy the code, return to the browser, and type it into the verification field - If you don't receive it within a few minutes, check your spam folder 9. You will land on a "Welcome to GitHub" personalization page - you can skip it or answer the questions; it does not affect your account functionality ### Verify your email address GitHub also sends a **separate** email verification link after account creation. Check your inbox for an email from GitHub with subject "Please verify your email address" and activate the link inside it. Some GitHub features (including creating repositories) require a verified email. ### Enable two-factor authentication (2FA): detailed guidance and workshop policy Two-factor authentication (2FA) adds a second verification step each time you sign in, protecting your account if your password is compromised. GitHub now requires 2FA for all accounts, so you may already have it enabled. If not, set it up now. We recommend using the **GitHub Mobile app** for the smoothest experience - see the options below. ### Quick steps to enable 2FA 1. Open the [GitHub security settings page](https://github.com/settings/security) while signed in. 2. Under **Two-factor authentication**, choose **Enable** and follow the prompts. 3. Choose one of the second-factor methods (recommended order): - **GitHub Mobile app** (recommended for this workshop): Install the free [GitHub Mobile](https://github.com/mobile) app on your phone. Once linked to your account, GitHub sends a push notification to your phone each time you sign in. You simply tap **Approve** - no codes to type. The app is available for iOS and Android and supports VoiceOver and TalkBack. - **Authenticator app**: Microsoft Authenticator, Google Authenticator, Authy - generates time-based 6-digit codes. - **Security key / passkey** (most secure): hardware security keys (YubiKey, etc.) or platform passkeys (biometric device credentials). - **SMS / text message** (least preferred): can be used if other options are unavailable. ### Detailed setup notes - Authenticator app (recommended): - Visual users: scan the QR code with your authenticator app and enter the 6-digit code shown. - Screen reader users: choose the link labeled **"enter this text code"** or **"can't scan the barcode?"** to reveal the secret (a 32-character key). Use the authenticator app's manual/key-entry option to add the account. - Security key / passkey: - Follow the on-screen prompts to register a hardware key or platform passkey. These are highly recommended for long-term security and are supported by modern browsers and devices. - SMS / text message: - Enter your phone number and verify the code sent via text. Use only if authenticator apps or keys are unavailable. ### Recovery and backup - After enabling 2FA, GitHub will display **recovery (single-use) codes**. Immediately copy, download, or securely store these codes (password manager or physically secure location). They are the only fallback if you lose your second-factor device. - Consider registering more than one second-factor method (e.g., authenticator app + a hardware key) to avoid account lockout. ### Authenticating Git with GitHub: browser-based sign-in (OAuth) When you use Git inside VS Code or GitHub Desktop, you do not need to manage passwords, tokens, or SSH keys manually. These tools use **browser-based OAuth sign-in** - the same "Sign in with GitHub" flow you use on any website: 1. The first time you push or pull code, VS Code (or GitHub Desktop) opens your default web browser to a GitHub authorization page. 2. Sign in to GitHub in the browser (including your 2FA step - a push notification if you use GitHub Mobile, or a code from your authenticator app). 3. Approve the authorization request. 4. Switch back to VS Code. Your credentials are securely stored by your operating system's credential manager, so you will not be prompted again on this machine. That is it. No tokens to generate, no keys to create, no strings to paste. If you are using GitHub Mobile for 2FA, the entire flow is: type your password, tap **Approve** on your phone, and you are authenticated. > **Screen reader note:** The authorization page opens in your default browser. After approving, the browser shows a message saying you can return to VS Code. Use `Alt+Tab` (Windows) or `Cmd+Tab` (macOS) to switch back. > **Default browser warning:** VS Code opens the GitHub authorization page in your operating system's **default browser**, not necessarily the browser you use day-to-day. If your default browser is set to something unexpected (for example, an older browser without your screen reader configured), the OAuth page may open in an unfamiliar environment. > > **Before the workshop:** Verify which browser is your OS default: > - **Windows:** Settings, Apps, Default apps, look for "Web browser" > - **macOS:** System Settings, Desktop and Dock, Default web browser > > Set it to the browser where your screen reader and GitHub login are already configured. This avoids a confusing moment during the first `git push` when the authorization page opens somewhere you did not expect. > **Tip - GitHub Mobile for push notification 2FA:** If you have not already, install the free [GitHub Mobile](https://github.com/mobile) app (iOS and Android). Once linked to your account, every 2FA prompt becomes a single tap on a push notification instead of typing a 6-digit code. The app supports VoiceOver (iOS) and TalkBack (Android). ### Workshop policy For this workshop, participants need a GitHub account with 2FA enabled. The browser-based sign-in described above handles all Git authentication automatically - no additional setup is required beyond having a working GitHub account. If you run into any authentication issues before the workshop, contact the workshop organizers at the email or issue link in this guide so we can help. ## Step 2 - Configure GitHub Accessibility Settings These settings make GitHub significantly more usable with a screen reader. **Do not skip this section** - one setting in particular (hovercards) adds significant noise to every page if left on. ### Navigate to Accessibility Settings The fastest path for everyone: navigate directly to **[GitHub Accessibility Settings](https://github.com/settings/accessibility)** while signed in. If you prefer to navigate through the interface:
Visual / mouse users 1. Click your **profile picture** (avatar) in the top-right corner of any GitHub page 2. A dropdown menu appears - click **Settings** 3. On the Settings page, scroll the **left sidebar** and click **Accessibility**
Screen reader users (NVDA / JAWS) 1. On any GitHub page, switch to Browse Mode if you are not already in it (`NVDA+Space` / JAWS virtual cursor should be on by default in browsers) 2. Press `B` repeatedly until you hear **"Open user navigation menu, button"** (top-right of the page) and press `Enter` 3. Navigate the menu with `↓` or `K` until you hear **"Settings"** and press `Enter` 4. On the Settings page, press `D` to move through landmark regions until you reach the left sidebar navigation 5. Press `K` or `↓` to navigate through sidebar links until you hear **"Accessibility"** and press `Enter`
Screen reader users (VoiceOver on macOS) 1. Press `VO+U` to open the Rotor, arrow to Buttons, find **"Open user navigation menu"** and press `Enter` 2. Press `VO+Down Arrow` to find **"Settings"** and press `VO+Space` 3. On Settings, press `VO+U`, go to Links, find **"Accessibility"** and press `Enter`
### Settings to configure Work through each setting below. All are on the [Accessibility settings page](https://github.com/settings/accessibility) unless noted. #### 1. Disable Hovercards (highest priority) > **Do this first.** Hovercards are the most disruptive default setting for screen reader users on GitHub. When enabled, every link announces its hover keyboard shortcut (`H`) as you navigate past it, dramatically slowing page reading.
Visual / mouse users On the Accessibility settings page, look for a checkbox or toggle labeled **"Link previews"** or **"Hovercards"**. If it is turned on, click it to turn it off. The change saves automatically.
Screen reader users 1. On the Accessibility settings page, switch to Browse Mode if not already active 2. Press `F` or `X` to jump through form controls until you hear **"Link previews"** or **"Hovercards"** 3. If it is announced as **checked** or **on**, press `Space` to turn it off 4. The change saves automatically - no Submit button required
#### 2. Enable Link Underlines
Visual / mouse users Find the **Link underlines** checkbox or toggle and turn it on. This adds underlines to all links on GitHub, making them distinguishable without relying on colour alone.
Screen reader users 1. Press `F` or `X` to navigate form controls until you hear **"Link underlines"** 2. If it is announced as **unchecked**, press `Space` to enable it 3. The change saves automatically
#### 3. Character Key Shortcuts 1. Find **"Character key shortcuts"** 2. Single-key shortcuts (`H` for next heading, `I` for next issue, etc.) speed up navigation but **can conflict with screen reader quick-navigation keys** - If your screen reader uses letters for navigation in Browse Mode (NVDA, JAWS), GitHub's single-key shortcuts are suppressed when Browse Mode is active, so conflicts are rare in practice - If you notice unexpected behavior, return here and turn them off 3. Leave at the default unless you have a reason to change it #### 4. Set Your Theme (Appearance Settings) Theme is on a separate page: [GitHub Appearance Settings](https://github.com/settings/appearance) 1. Navigate to that page 2. Find the **"Theme mode"** or **"Theme"** section 3. Options available: - **Light default** - standard white background - **Dark default** - dark background, easier on some eyes - **High contrast light** - maximum contrast, recommended for low vision - **High contrast dark** - maximum contrast on dark background - **Colorblind** variants - Protanopia, Deuteranopia, Tritanopia 4. Select your preferred theme and activate **Save** if prompted (some changes apply immediately) ## Step 3 - Configure Your Profile Your GitHub profile is your public identity in the open source community. Setting it up properly helps maintainers know who you are. ### Who are maintainers? Maintainers are the people who manage a repository -- they review contributions, respond to issues, merge pull requests, and keep the project running. When you open an issue or submit a pull request, a maintainer is the person who will see it and respond. Setting up your profile helps maintainers know who you are and builds trust in the community. ### Update your profile 1. Navigate to [Settings → Public profile](https://github.com/settings/profile) 2. Fill in: - **Name** - your real name or display name (not the same as your username) - **Bio** - a short description (e.g., "Accessibility advocate and open source contributor") - **Location** - optional but builds trust in the community - **Website or social links** - optional - **Pronouns** - GitHub supports adding pronouns to your profile ### Add a profile picture (strongly recommended) A profile picture is strongly recommended because it humanizes your contributions and helps maintainers and collaborators recognize you across issues, pull requests, and comments. It can be a photo or any image that represents you. If you prefer not to use a photo, GitHub generates a default avatar based on your username. ### Set your notification email 1. Navigate to [Settings → Notifications](https://github.com/settings/notifications) 2. Add a **custom routing** email if you want GitHub notifications to go to a different address than your account email ## Step 4 - Check GitHub Feature Preview Settings GitHub continuously rolls out improvements to its interface. Some enhancements start as opt-in Feature Previews before becoming the standard experience. Three features matter most for screen reader users working through this workshop: - **New Issues Experience** - improves heading hierarchy, ARIA landmark structure, and live-region announcements on the Issues pages - **New Files Changed Experience** - adds proper landmark structure, an accessible file tree, and better keyboard navigation to the Files Changed tab in Pull Requests - **GitHub Command Palette** - a keyboard-first command launcher (`Ctrl+K` on Windows, `Cmd+K` on macOS) that lets you navigate to any repository, issue, PR, file, or page by typing its name. Faster than clicking through menus and fully accessible with screen readers Both have been broadly rolled out and may already be active on your account. Check before the workshop begins. ### How to Check and Enable Feature Previews > Source: [accessibility.github.com/documentation/guide/issues/](https://accessibility.github.com/documentation/guide/issues/) and [accessibility.github.com/documentation/guide/pull-requests/](https://accessibility.github.com/documentation/guide/pull-requests/)
Visual / mouse users 1. Sign in to GitHub and go to any page 2. Click your **profile picture** (avatar) in the top-right corner 3. In the dropdown menu, click **Feature preview** 4. A panel opens on the right side of the screen listing available features 5. Click on **New Issues Experience** to expand its details 6. If an **Enable** button appears, click it. If you see **Disable**, the feature is already active - no action needed. 7. Return to the feature list and repeat for **New Files Changed Experience**
Screen reader users (NVDA / JAWS) #### NVDA or JAWS (Windows) 1. Sign into GitHub and open any page 2. Switch to Browse Mode if not already active (`NVDA+Space` / JAWS virtual cursor) 3. Press `H` or `Shift+H` to navigate to the **"Navigation Menu"** heading, or press `D` to navigate landmark regions to the navigation section 4. Press `B` to jump to buttons, navigating until you hear **"Open user navigation menu, button"** - this button is in the top-right corner of the page 5. Press `Enter` to activate it - a dropdown menu opens 6. Press `↓` or `K` to move through the menu items until you hear **"Feature preview"** 7. Press `Enter` to select it - the Feature Preview panel opens 8. Navigate through the list of features with `↓` or `I` (list item navigation) 9. When you reach **"New Issues Experience"**, press `Enter` or `Space` to select it - its detail panel expands 10. Press `Tab` to move to the end of the feature detail section, where you will find either: - An **"Enable"** button - press `Enter` to enable the feature - A **"Disable"** button - the feature is already enabled; no action needed 11. Go back and repeat steps 9-10 for **"New Files Changed Experience"** 12. Repeat again for **"GitHub Command Palette"** if it appears in the list
Screen reader users (VoiceOver on macOS) 1. Sign into GitHub and open any page 2. Press `VO+U` to open the Rotor and navigate to the Buttons list 3. Find **"Open user navigation menu"** and press `Enter` to activate it 4. Use `VO+Down Arrow` to navigate the dropdown until you hear **"Feature preview"** 5. Press `VO+Space` to activate it - the Feature Preview panel opens 6. Use `VO+Down Arrow` or `VO+Right Arrow` to navigate through the feature list 7. When you reach **"New Issues Experience"**, press `VO+Space` to select it 8. Press `Tab` to move to the end of the feature detail section 9. If you hear **"Enable"**, press `VO+Space` to activate it. If you hear **"Disable"**, it is already on. 10. Repeat for **"New Files Changed Experience"** 11. Repeat for **"GitHub Command Palette"** if it appears in the list
### What "Not Listed" Means If you open Feature Preview and neither **"New Issues Experience"** nor **"New Files Changed Experience"** appears in the list at all - that is good news. It means both features have **graduated to the standard GitHub interface** and are active automatically for every user. No action needed. ### What Each Feature Enables | Feature | What it improves for screen reader users | | --------- | ------------------------------------------ | | **New Issues Experience** | Issues list uses proper `