Installation Instructions and Set-Up

Getting Started with GitHub

1 Create your GitHub Account

As part of this workshop we will be connecting and pushing some sample code to GitHub, therefore you’ll need to create a GitHub account. In general, creating a GitHub account can be a great way to collaborate on open-source projects, showcase your work, and learn from others.

  1. Go to https://github.com and click “Sign up” at the top-right of the window.
    • Note that this does NOT have to be your BC gov email (but if you want one just for government use, feel free to use your BC gov email).
    • If you already have a personal GitHub account, that is just fine! This can be connected to your BC gov email at a later date.
  2. Follow the step-by-step instructions to create an account.
  3. Verify your email address with GitHub.

Optional reading: Configuring your GitHub account

2 Login to your GitHub Account

When we sign in to GitHub on the web, we are signing into our application account created in step 1. This is where we manage our profile settings, set our passwords, and browse repositories. It is possible to edit repository content from GitHub although editing is often performed in a local application such as RStudio, VS Code or a text editor. We will go into more detail on that in the course workshop.

  1. Go to https://github.com/ and click “Sign In” (top right corner).
  2. Enter either your username or your email address, and password created in Step 1.

3 Configure Multi-Factor authentication (2FA)

As of 2023 all GitHub accounts are required to have multi-factor authentication (2FA) configured for extra security. Several options exist for setting up 2FA, the simplest is via text message described below.

  1. In the upper-right corner of any page, click on your profile photo/avatar and select Settings.
  2. In the “Access” section of the sidebar, click on Password and authentication.
  3. Scroll down to “Two-factor authentication” section of the page and click Enable two-factor authentication.
  4. At the bottom of the page, next to “SMS authentication”, click Select.
  5. Complete the CAPTCHA challenge, which helps protect against spam and abuse.
  6. Under “Setup SMS authentication”, select your country code and type your mobile phone number, including the area code. When your information is correct, click Send authentication code.
  7. You’ll receive a text message with a security code. On GitHub, type the code into the field under “Verify the code sent to your phone” and click Continue.
  8. If you need to edit the phone number you entered, you’ll need to complete another CAPTCHA challenge.
  9. Under “Save your recovery codes”, click Download to download your two-factor recovery codes to your device. Save them to a secure location because your recovery codes can help you get back into your account if you lose access.
  10. After saving your two-factor recovery codes, click “I have saved my recovery codes” to enable two-factor authentication for your account.

Optional reading: Other 2FA configurations.

4 Create a Personal Access Token

To keep your account secure, you must authenticate before you can access certain resources on GitHub. When we access resources via a browser (as in Step 2) we are authenticating with our username and password and two-factor authentication. In the workshop we will also be accessing GitHub resources via the REST API. You can authenticate with the API in different ways, but the simplest way is with a Classic Personal Access Token (PAT).

First verify your email address (if it hasn’t been verified yet):

  1. In the upper-right corner of any page, click your profile photo, then click Settings.
  2. In the “Access” section of the sidebar, click Emails.
  3. Under your email address, click Resend verification email.
  4. GitHub will send you an email with a link in it. After you click that link, you’ll be taken to your GitHub dashboard and see a confirmation banner.

Then create your PAT:

  1. In the upper-right corner of any page, click your profile photo, then click Settings.
  2. In the left sidebar, click Developer settings.
  3. In the left sidebar, under Personal access tokens, click Tokens (classic).
  4. Select Generate new token, then click Generate new token (classic).
  5. In the “Note” field, give your token a descriptive name. At some point you may use a second PAT and a name helps keep things straight but for now you could name it “work-2023” or “november-2023”.
  6. To give your token an expiration date, select Expiration. For first time users, 30 days is a good choice, after which time GitHub will send an email notification reminding you to renew your PAT.
  7. Select the scopes you’d like to grant this token. The repo and user boxes should be sufficient for the workshop and most cases in general.
  8. Click Generate token.
  9. Copy the new token to your clipboard and save to a text file for later.

Optional reading: Authenticating to the REST API

5 Install Git (and GitBash)

Git is a set of command line utility programs that are designed to execute on a Unix style command-line environment. Linux and MacOS both include built-in Unix command line terminals. Most likely you are working on a Windows operating system and will require Git Bash, an application for Windows environments which provides an emulation layer for a Git command line experience.

Windows

  1. Search for “Git Bash” in your start menu to check if Git/GitBash are already installed on your computer.
  2. If Git/GitBash are not installed, navigate to Git for Windows and click “Click here to download” to download the latest 64-bit version of Git for Windows software. This software includes GitBash
  3. After the download is complete, double click on it to run the installer. The Git Setup wizard will appear. Follow the on-screen prompts by clicking “Next” and “Finish” to complete the installation. The default options are suitable for most users with the following exceptions:
    • Select Notepad++, Notepad or Wordpad to use as your default editor.
    • Adjust the name of the initial branch in new repositories. Override the default to use “main” instead of “master”.

MacOS

Please visit: Installing Git and follow the instructions for installing git for MacOSX.

6 Configure Git

6.1 Git Set Up

When we use Git on a new computer for the first time, we need to configure a few things. Below are a few examples of configurations we will set as we get started with Git:

  • our name and email address
  • and that we want to use these settings globally (i.e. for every project).

On a command line, Git commands are written as git verb options, where verb is what we actually want to do and options is additional optional information which may be needed for the verb.

6.2 Set user.name & user.email

In this workshop, we’ll be working with GitHub, and it’s important to ensure that the name and email address you configure on your local computer matches the one associated with your GitHub account. For most participants, this will be your government email address.

Below is an example configuration that we will use to connect your local git instance with GitHub.

For Windows users, these will be typed into a Git Bash terminal (search for Git Bash from the search bar to open a new window). For Mac users, these will be typed into the Terminal.

$ git config --global user.name "your GitHub account name" 
$ git config --global user.email "your_email@gmail.com"

If you are concerned about privacy, please review GitHub’s instructions for keeping your email address private.

6.3 Check Global Settings

The two commands we just ran only need to be run once. The flag --global tells Git to use the settings for every project on this computer.

You can check your settings at any time with:

$ git config --list

You can change your configuration as many times as you want: use the same commands to update your name or email address.

6.4 Access Git Help and Manual

If you forget a git command, you can access a list of available commands by appending a -h. You can access the Git manual for a command by appending --help :

$ git config -h
$ git config --help

While viewing the manual, you may see : near the cursor at the bottom of the screen. This is a prompt waiting for further commands such as Q, which you can use to exit the manual.

Additional Resources

https://github.com/bcgov/BC-Policy-Framework-For-GitHub