Setup

What you need before the session, how to choose the browser or the command line, and what to do if something is missing.

Each exercise has a browser route and a command-line route. The browser route needs no software, and neither route needs homework. For both routes, you need three things.

You need Why If you do not have it
A laptop with a current desktop browser The GitHub interface hides parts of the menus on a phone. Share a laptop with a neighbour.
A GitHub account Every exercise creates something in your account. Create one at the start (allow 10 minutes), or work in a pair.
Two-factor authentication that works on the day GitHub asks for a second factor at sign-in. Bring the device or the recovery codes that you use for GitHub.

Create a GitHub account

If you have no account yet, create it before the session if you can.

  1. Open github.com/signup.
  2. Use an e-mail address that you can open during the session.
  3. Choose a username that you are comfortable to show in public. Your username appears on every repository and Issue.
  4. Confirm the e-mail address.
  5. Set up two-factor authentication when GitHub asks for it.

The free plan (GitHub Free) is sufficient. Students can also apply for GitHub Education, but the workshop does not need it.

Choose your path

Before X1, decide how you work. You can change the decision later.

Path Who it is for What changes
Solo, public Default Your exercise repository and Project are public. They contain only synthetic data.
Solo, private You do not want public activity under your name. Select Private for the repository and the Project. All exercises work the same way.
Pair You have no account, or you prefer to work together. One person owns the repository and the Project and gives the partner access to both. You review each other’s pull requests in X4.

Work in a pair

Repository access and Project access are separate. Access to the repository does not give access to the Project. The owner gives both.

  1. In X1, open the repository and click Settings.
  2. Under Access, click Collaborators, then Add people.
  3. Search for your partner and add them. Your partner accepts the invitation.
  4. In X3, open the Project. Click … (top right), then Settings.
  5. Click Manage access. Under Invite collaborators, search for your partner.
  6. Select the role Write and click Invite.

A partner without an account works on the owner’s laptop. Swap the keyboard at each exercise.

Choose your route

Each exercise reaches the same result on two routes. The path above decides what you share. The route decides how you work.

Route You need Choose it when
Browser A current desktop browser GitHub is new to you, or you cannot install software on your laptop.
Command line git, gh (the GitHub command-line tool), a terminal, and a text editor You know some command line, or you want to learn the workflow for your own computer.

Each exercise shows the routes as two tabs: Browser and Command line. When you select a tab, all tabs on the page switch together. A step without a usable command says Browser only. Both routes change the same repository on GitHub, so you can change the route at any step. The cheat sheet explains what git does.

Prepare the command line

Do this before the session. Allow 15 minutes. If a step fails, use the browser route. You lose nothing.

  1. Install git from git-scm.com/downloads. On Windows, the installer also installs Git Bash.

  2. Install gh from cli.github.com. The instructor tested the exercises with gh 2.102.0. Install this version or a later one.

  3. Open a terminal. On Windows, open Git Bash, because the commands on this site use its syntax.

  4. Check both tools. Each command prints a version number.

    git --version
gh --version

  5. Sign in to GitHub in the browser window that gh opens. The option --scopes project gives gh access to Projects.

    gh auth login --hostname github.com --git-protocol https --web --scopes project

  6. Let git use the sign-in of gh when it sends commits to GitHub:

    gh auth setup-git

  7. Set the name and the e-mail address that git writes into each commit. Use your no-reply address from Settings → Emails on GitHub.

    git config --global user.name "Your Name"
git config --global user.email "ID+USERNAME@users.noreply.github.com"

  8. Check the sign-in. The line “Token scopes” includes project.

    gh auth status

If you signed in to gh before, add the access to Projects with gh auth refresh -s project.

Each commit shows its name and e-mail address to everyone who can see the repository. The no-reply address keeps your private address private (Setting your commit email address).

You also need a text editor for Markdown files. Any editor that saves plain text works, for example Visual Studio Code.

Command-line problems

Problem Cause Recovery
“command not found: gh” or “command not found: git” The tool is not installed, or the terminal opened before the installation. Open a new terminal. If the error stays, install the tool again.
“fatal: not a git repository” The terminal is not in the project folder. Run cd projm-thesis.
gh reports that the token is missing the scope project. You signed in without access to Projects. Run gh auth refresh -s project.
git push asks for a user name and a password. git does not use the sign-in of gh. Run gh auth setup-git. Then push again.
git push is rejected with “fetch first”. GitHub has commits that your computer does not have, for example from the browser route. Run git pull --rebase. Then push again.
An editor opens in the terminal. git asks for a message. In nano, press Ctrl+X. In vim, type :wq and press Enter.
“command not found: issue” The terminal is new, and the helper issue is not defined in it. Define the helper again, as in X3.
Another error — Do the step in the browser. Both routes reach the same state.
ImportantSynthetic data only

Do not put real personal data, unpublished research data, or third-party material into an exercise repository. The workshop gives you a synthetic dataset. For your real thesis, start with a private repository and a private Project. See Transfer to a private thesis.

What to open on the day

Official documentation

Back to top