Installation Instructions and Set-Up

1 Getting Started with GitHub

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

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

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

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

1.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 see if Git/GitBash are installed on your computer already.
  2. If not, navigate to Git for Windows and click “Click here to download” to download Git/GitBash bundled software. Choose the first link, that will download the latest 64-bit version of Git for Windows.
  3. When you’ve successfully started the installer, you should see the Git Setup wizard screen. Follow the Next and Finish prompts to complete the installation. The default options are pretty sensible for most users.

MacOS

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

1.6 Configure Git

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.

Set user.name & user.email

In our workshop, we will be interacting with GitHub and so our configured email address should be the same as the one used when setting up your GitHub account. Most likely this will be your government email.

Below is an example configuration, please type in the commands using your name and email address. For Windows users, these will be typed into a Git Bash terminal (search for Git Bash from the search bar to create a new window). For Mac users, these will be typed into the Terminal.

$ git config --global user.name "Your Name in Quotes"
$ 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.

Global Settings

The two commands we just ran above only need to be run once: the flag --global tells Git to use the settings for every project, in your user account, on this computer.

You can check your settings at any time:

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

Git Help and Manual

Always remember that if you forget a git command, you can access the list of commands by using -h and access the Git manual by using --help :

$ git config -h
$ git config --help

While viewing the manual, remember the : is a prompt waiting for commands and you can press Q to exit the manual.

2 Additional Resources

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