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.

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

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 https://github.com/login/device as instructed.

4. Authorise the hub to access GitHub by clicking the green Authorize <name of hub> button.

5. Install the hub’s GitHub App to allow gh-scoped-creds for all or specific repositories you would like to push to that are owned by your GitHub account/organisation, and check that Read and write access to code option is enabled.

6. 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.

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 install 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 Install button.

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