Ctrl+K

Set up git access

Set up git access#

Ian Fenty and Andrew Delman, updated 2024-10-11

This tutorial helps you set up git on Open Science Studio (OSS), with the identity information and authentication keys that you need in order to: 1) pull changes from GitHub to your OSS workspace, and 2) contribute changes back to GitHub.

What is git
Setting up on JupyterHub
Authenticating with GitHub

What is git?#

Git is a popular version control system that is used in many open source software projects to manage their software code base.

Note

You are not required to know git in advance of this event, but come prepared to learn a lot about it! Here is a quick introduction video from the official website

Note

Installing git on your local computer

If you want to use and setup git on your local computer and don’t have the command available in your local terminal, you can download the latest installer on Git-SCM. More help for the install process can be found in the official Git documentation

Setting up on JupyterHub#

Below are instructions to get you setup with git on the OSS JupyterHub. These are only basic instructions to get started. See the Software Carpentry Git instructions for a more thorough explanation and background information.

1. Login to JupyterHub#

Go to https://sealevel.oss.eis.smce.nasa.gov. See also our OSS JupyterHub introduction.

2. Open a Terminal#

Choose the ‘Terminal’ from the ‘Other’ options in the ‘Launcher’ tab.

jupyterlab

3. Configure git on OSS#

Set your username and email address. The email address should be the same as you used to register your GitHub account.

Attention

Use your personal name instead of the placeholder Attendee Name in the below commands. For the email, it should be the address you used to create your GitHub account instead of attendee@hackweek.com. Both values need to be surrounded by quotes ".

git config --global user.name "Attendee Name"
git config --global user.email "attendee@hackweek.com"
git config --global pull.rebase false
git config --global credential.helper store
git config --global http.postbuffer 524288000

The third line is a configuration option that needs to be done with a first time setup. It specifies the strategy on how git will apply changes you pull from a remote git repository. More on strategies is described here.

The fourth line of the config will store your GitHub credentials and will save you from re-entering your username and password from the command line with each push, pull, or interactions with GitHub. The fifth line sets a high limit (~500 MB) for the repository size that you can clone/pull to or push from your local system. All of these settings are saved in a ~/.gitconfig file in your user home directory.

To verify that you successfully executed the above commands, use the

git config -l

command.

The output should look similar to this:

jovyan@jupyter:~$ git config -l
user.name=Attendee Name
user.email=attendee@hackweek.com
credential.helper=store

Authenticating with GitHub#

This section covers two different methods for authenticating with GitHub, so that GitHub knows who you are when interacting with a repository and contributing code. More detailed instructions can be found here.

Option 1: Set up Personal Access Token (HTTPS access)#

A GitHub Personal Access Token can be used to clone, pull, and push GitHub repositories. This offers customizable permissions and can be revoked without affecting your main GitHub user account password.

Take a moment to work through the instructions on the GitHub personal access tokens (classic) page. For this hackweek, you need to check the repo, admin:org, and workflow scope.

Screenshot from github.com setting up the token: github-token

Once you have created your token, be sure to save it on your computer in case you need to re-authenticate again. The token will give you access to your personal GitHub account. It will also give you permission to push changes to your project repository within the ECCO HackWeek hackweek organization via the command line.

To test your setup on the JupyterHub, we will be using a test repository from the UW Geohackweek organization. Enter the following command into your open terminal on the JupyterHub, replacing {username} with your GitHub username and {TOKEN} with the token you just created.

    git clone https://{username}:{TOKEN}@github.com/NASA-Openscapes/check_github_setup.git

Attention

The inclusion of {username}:{TOKEN}@ is optional. Typically you can clone a repository without including your credentials, but when pushing edits back to the repo GitHub will prompt you for the credentials if they are not already stored.

Because you already set credential.helper store earlier, you only should need to enter these credentials once on a given machine. Next time you clone a repo, you can omit {username}:{TOKEN}@, for example: git clone https://github.com/NASA-Openscapes/check_github_setup.git.

Browser context menu

The browser context menu that offers the copy and paste option via right-click of your mouse is accessible on the JupyterHub by using the ‘Shift’ key.

Now that you have entered your credentials once, you should no longer be prompted for your username and token again. To test the successful storage of your credentials, go inside the repository and issue a git pull command. If successful, you should have an output similar to this:

# Go inside the directory
(notebook) jovyan@jupyter:~$ cd check_github_setup/
# Issue the pull command
(notebook) jovyan@jupyter:~/check_github_setup$ git pull
Already up to date.

With the git command successfully set up, you can now remove the test repository.

Danger

Be careful with the rm -rf command. There will be no confirmation prompt for this action and files and folders removed with this command are not recoverable.

rm -rf check_github_setup

Option 2: Set up SSH key (SSH access)#

The following steps will enable you to interact with GitHub repositories from your local machine via the Secure Shell (SSH) protocol.

  1. Log into the OSS JupyterHub (https://sealevel.oss.eis.smce.nasa.gov).

  2. Open a new terminal window: Instructions

    • Method 1: Toolbar –> File –> New –> Terminal

    • Method 2: Click the blue + button in the file browser –> select the $_ Terminal Button

  3. Generate a new SSH public/private key pair. Use the email address associated with your github account.
    ssh-keygen -t ed25519 -C "your.email@example.com"

    • if you use the default filenames you will get id_ed25519.pub (public key) and id_ed25519 (private key) in /home/jovyan/.ssh

    • you can hit enter when asked for a passphrase for no pass phrase

    • make sure that only you can read the private key: chmod 400 ~/.ssh/id_ed25519. Otherwise you may get an error when using the key pair later.

  4. Add the new SSH public key to your GitHub account. Detailed Instructions

    • Log into your github account

    • click on your profile picture (usually in the top right corner of the github page)

    • click Settings

    • click on SSH and GPG keys on the left hand side

    • click on Green button: “New SSH Key”

    • Make a title, something like ECCO_HackWeek

    • Key type should be “Authentication Key”

    • Copy the contents of your public key file on OSS (id_ed25519.pub) to the clipboard

      • Return to the OSS JupyterLab terminal window

      • Show the contents of the public key file to the screen: cat ~/.ssh/id_ed25519.pub

      • select the text, ssh-ed25519 .... your.email@example.com, and copy (Ctrl-C or equivalent)

    • Paste the text in the Key text box in the GitHub Add new SSH Key page

    • Click the Green button: “Add SSH key”

    • Verify the new key appears on the list of “SSH keys” on the GitHub SSH keys page

(Optional) Advanced GitHub setup#

In addition to interacting with GitHub via the git command, you can also use the gh command, which is a set of command line tools developed by GitHub to interact with their website from the command line.

To set this up, use the gh auth login command and your access token. The answers to each question are shown in the output below.

(notebook) jovyan@jupyter-jomey:~$ gh auth login
? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Paste an authentication token
Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo', 'read:org', 'workflow'.
? Paste your authentication token: ****************************************
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as ECCO_Hackweek
Contents