GitHub basics

GitHub basics#

Overview#

These notes cover the basics for using GitHub in this class.

Branch management#

How to create repository branches using various tools.

Creating a branch using the GitHub website#

You can add branches to your repository directly by clicking the “Branches” icon, and then “New Branch” on the subsequent window (screenshots below).

You’ll need the following information:

  • New branch name: the lab name (e.g. lab-1).

  • Source: the instructions branch from your own repository

Creating a new branch
Naming a new branch

The user interface for creating branches on GitHub.#

Creating a branch using VSCode#

You can create branches within your project using VSCode:

Clicking on the branch button (bottom left) launches a dialog which allows for a few branch operations: you can create a new branch, switch to a local branch, switch/pull a remote branch, etc.#

Creating a branch using the command line#

# make sure you are on the `instructions` branch before proceeding
git status
# the switch command switches branches, -c flag stands for "create"
git switch -c lab-1
# upload your branch to the remote repository
git push -u origin
# ensure your new lab-0 branch is up to date with new remote lab-0 branch
git status

GitHub Authentication#

Many git operations require authentication to get permission. Some examples:

  • Pushing to a repository

  • Pulling from a private repository

  • Using GitHub CLI

Since July 2021, GitHub no longer accepts account passwords to authenticate git operations. You have probably run into this error many times when trying to push changes or clone your private repositories on a new machine.

The only reason VSCode works out of the box is because VSCode and GitHub are integrated by default, both being owned by Microsoft.

The following sections gives us more flexible and useful ways to authenticate git commands with GitHub.

Creating a personal access token#

Read “Managing your personal access tokens” on Github, and create a classic (not fine-grained) personal access token.

At the very least, select the repo scope – this will give your token the ability to authenticate using git on the CLI. You can select all other scopes as well if you like.

Once you’re finished, you’ll see your token is a string of the following form:

ghp_<long string of letters and numbers>

Keep this window open – the string of characters will disappear as soon as you refresh the page.

We need to configure a secure storage location for this string. For this, we will use the tool pass.

Using a password manager to store your token#

Secrets like personal access tokens need to be readily accessible to be useful – but they also should be secret, so that others cannot easily impersonate you using the token.

A common method for managing secrets is to use a password manager. In our course we use pass to securely manage our personal access tokens on our developer environment.

Install pass dependencies#

First, ensure pass and some useful related dependencies are installed:

# On WSL / Linux
sudo apt install pass pass-extension-otp zbar-tools

# On macOS
brew install pass pass-otp zbar

Set up gpg#

pass works by using asymmetric key encryption to store secrets. That means: you posess the private key that can decrypt secrets, and you make the public key available which can encrypt secrets.

This scheme is not only useful for private communication (something similar is used by apps like Signal and Telegram), but also for storing any secrets – for us, we will store our github token as a secret.

To get started, you’ll need to generated a gpg key-pair in order to use pass.

Note

The GitHub instructions mention using git bash – ignore them, you have a developer environment to use instead.

In general, when I link to external instructions, you will need to pay attention to what parts of them may be different in our class. This is a good skill in general for making effective use of resources posted online when learning a new skill.

Follow the instructions below:

  1. Create the gpg key-pair following the instructions on GitHub: Generating a new GPG key

  2. run gpg --full-generate-key to get started.

  3. Recommended: You can accept the default key type (RSA)

  4. Recommended: Choose 4096 bits for the keysize.

  5. Recommended: You can accept the default “does not expire” option.

  6. Enter user ID information. This information should match what you have provided to GitHub already (username/email address)

  7. You have to choose a password for GPG keys. Choose something strong that you can remember.

  8. Add the public key to your GitHub account following the instructions: Adding a GPG Key to your GitHub account.

The name of the key on GitHub does not matter (Personal GPG Key is fine)

The command: gpg --armor --export prints your key to the console, you can copy/paste this output for GitHub

Even better: use a pipe to clip.exe to put the key in your clipboard automatically with gpg --armor --export | clip.exe

  • on macOS: use pbcopy instead of clip.exe

  • on Linux: use xclip or wl-copy instead of clip.exe

Store personal access token in pass#

Once you’ve created the gpg key-pair, we can now set up pass:

pass init <the-email-you-used-for-gpg-key>

Finally, copy the token string from GitHub to your clipboard. Then, open your developer terminal:

$ pass insert github/token
Enter password for github/token: # paste your token here, then press enter

Once you’ve done this, you should be able to access your token using pass github/token, or pass github/token | clip.exe to place it on your clipboard directly.

Troubleshooting#

Some common errors that arise with using gpg:

No secret key#

This error looks like:

$ pass github/token
gpg: decryption failed: No secret key

Try the following:

Double check the password store setup#

Confirm that your password store is encrypted with the gpg key you expect:

# This command prints out your gpg key information
$ gpg -k 

# This command shows the gpg key used to encrypt your password-store
$ cat ~/.password-store/.gpg-id

# The id and/or email address should match for both!
Restart gpg daemon#
$ gpgconf --kill gpg-agent

If that doesn’t work, try restarting your WSL instance. In powershell:

powershell#
PS > wsl --shutdown <distro-name>

After the shutdown attempt, retry using pass in the WSL again.

Developer environment setup   L1: Developer Environment Setup
Contents