Move code in and out of the hub with GitHub

The recommended way to move code in and out of the hub is with GitHub.

A typical pull request git workflow (GitHub flow docs) for collaborating on code consists of:

1. Pulling code from a remote repository on GitHub to a local repository on your hub

2. Creating a new branch from your local repository for working on your changes

3. Recording your changes with new commits to your branch

4. Pushing the branch with changes to the remote repository on GitHub

5. Repeating steps 3. and 4. until your work is ready to be reviewed

6. Creating a pull request on the remote repository on GitHub for review.

Note

Git clone using the HTTPS protocol and not SSH, since on the hub HTTPS will always work behind a firewall or proxy.

When you pull and push code to the remote repository on GitHub, you will need to provide your GitHub credentials.

Warning

We do not recommend entering your GitHub credentials (GitHub password, personal access tokens or otherwise) on any kind of shared infrastructure (e.g. private and public cloud, HPC, any remote machine) as this information will be at risk.

We highly advise using gh-scoped-creds for authentication on our hubs.

Using gh-scoped-creds

Authorisation to pull and push to GitHub is handled with gh-scoped-creds.

1. Open a Terminal.

2. Run the command gh-scoped-creds.

3. The following prompt will appear

   jovyan@jupyter-username:~/my-repo$ gh-scoped-creds
   You have 15 minutes to go to https://github.com/login/device and enter the code: XXXX-XXXX
   Waiting....
   

   Copy the code from the prompt and paste into login/device as instructed.

4. Authorise the hub to access GitHub by clicking the green button with the label Authorize .

5. You should now be able to pull and push to GitHub from the hub without entering your credentials.

Authorisation will automatically expire after 8 hours (or when your JupyterHub server stops), and you’ll have to repeat these steps to renew.

Hint

If you receive a Permission denied error after following these steps, then gh-scoped-creds has not been enabled for your hub. Please contact your hub administrator to request this feature.

Enabling gh-scoped-creds for your hub

There are some extra steps for Hub Administrators to enable gh-scoped-creds for their hub (requires GitHub organisation owner permissions).

1. Check that gh-scoped-creds is not already enabled for your hub by opening a Terminal and running

   jovyan@jupyter-username:~$ echo $GH_SCOPED_CREDS_CLIENT_ID
   

   If this returns nothing, then follow the next step. If this returns a client ID of the form Iv1.xxxxxxxxxxxxxxxx, then go to Step 3.

2. Send a ticket to the 2i2c support desk and log a feature request for gh-scoped-creds. 2i2c will create a GitHub App and update the hub configuration to make the GH_SCOPED_CREDS_CLIENT_ID and GH_SCOPED_CREDS_APP_URL environment variables available in your hub.

3. Install the GitHub App to your GitHub organisation (requires GitHub organisation owner permissions).

   • Navigate to the GitHub App URL provided by 2i2c, which looks like https://github.com/apps/<gh-app-name>.

   • Click on the grey Configure button to install the GitHub app.

   • Select the GitHub organisation that you would like to enable gh-scoped-creds for

     

   • Choose whether to enable gh-scoped-creds for all repositories in your organisation or for only specific repositories, and check that Read and write access to code is enabled.

     

   • Click the green button labelled Install.

4. gh-scoped-creds is now enabled for your hub.

Note

If you wish to review the GitHub App settings, then you can locate your organization’s installed apps at https://github.com/organizations/<your-org-name>/settings/installations.