Using Git on the HPC

Who this is for: anyone who will clone or update repositories on the HPC, which is everyone running project work there. Before you start: you need a GitHub account in the EpiModel organization and the GitHub personal access token from Setting Up Your Computer.

Our project repositories and data packages (for example EpiModelHIV-p and ARTnetData) are private. The HPC needs two credentials for them: your GitHub personal access token, so R can install private packages, and an SSH key, so git can clone and pull.

GitHub personal access token on the HPC

Log in to the HPC and open (or create) ~/.Renviron:

nano ~/.Renviron

Add one line with your token, save (Ctrl+O, Enter), and exit (Ctrl+X):

GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx

Then make the file private. Home folders on the HPC can be read by other cluster users, and this file holds your token:

chmod 600 ~/.Renviron
ls -l ~/.Renviron     # should start with -rw-------

Do not copy your local .Renviron to the HPC with scp. It would replace any .Renviron already there, it would arrive readable by others, and on Windows R keeps it in a different folder anyway. When your token expires, installs from GitHub start failing with error 401; make a new token and update this line.

SSH key for GitHub on the HPC (required)

GitHub no longer accepts passwords for git, and our workflows clone and update project repositories on the HPC over SSH. So you need an SSH key on the HPC that is registered with your GitHub account. On the HPC:

ssh-keygen -t ed25519 -C "your_github_email@example.com"

Press Enter to accept the default file (~/.ssh/id_ed25519) and twice more to skip the passphrase. If you are ever asked whether to overwrite ~/.ssh/id_rsa, answer no: the cluster created that key for its own use, and replacing it breaks logins between nodes.

Print the public key and copy it:

cat ~/.ssh/id_ed25519.pub

Add it to GitHub under Settings > SSH and GPG keys > New SSH key (GitHub's instructions). Then test:

ssh -T git@github.com

The reply should start with Hi <your GitHub username>! You've successfully authenticated. The first time, type yes to trust GitHub's host key.

This is a different key from the one you made in Setting Up Your HPC Environment. That one lives on your computer and lets you into the HPC; this one lives on the HPC and lets the HPC into GitHub.

Git workflow

We write and change code on our own computers, push it to GitHub, and pull it on the HPC. We do not edit code on the HPC and push it back; keeping one direction avoids conflicts.

Cloning

To clone a repository means to download a copy of it for the first time. Go to your folder in the lab directory and clone with the SSH address:

cd /projects/epimodel/<netid>
git clone git@github.com:EpiModel/<repo>.git

replacing <repo> with the repository name. This makes a new folder that mirrors the repository on GitHub. Do not clone with an https:// address that contains your token; the token would be saved in plain text in .git/config.

Pulling

To update a repository you have already cloned, go into its folder and pull:

cd /projects/epimodel/<netid>/<repo>
git pull

Switching branches

To switch to another branch after pulling:

git checkout <branch>

Branch names are case-sensitive. Check where you are with git status --short --branch, which shows the branch and whether it is behind GitHub.

Next: Using R via Spack on the HPC.