Frequently asked questions

Can I automatically tell JupyterHub what kind of server to start (node size, profile name, etc) as part of my nbgitpuller link?

You can use Kubespawner’s profile_list or ProfileSpawner to allow your end users to choose the resources (memory, cpu, GPUs, etc) they want before starting their server. Wouldn’t it be nice if this information could be embedded in the nbgitpuller link, so this (often confusing) choice is made for your students?

While it would indeed be very nice, this is currently not easy for two reasons:

1. nbgitpuller is a Jupyter Server extension, and only runs after the server is started. It knows nothing about JupyterHub. So it can not influence the options JupyterHub uses to start the server.

2. There is UX complexity in what happens if the user clicks an nbgitpuller link when a server is already running, but with a different set of resource requests / profile options. Do we shut that existing one down? Just error? Do nothing? Many valid options, but takes a bunch of work.

So while this workflow is possible, it would most likely be done at the JupyterHub level to make it possible, rather than in nbgitpuller

Common errors

Malformed links

Errors from clicking an nbgitpuller link usually stem from a malformed link, such as a mistake in the:

1. Source content repository link, such as pasting the wrong link into the Git Repository URL form field of the nbgitpuller link generator

   • Wrong ❌ https://github.com/owner/repo/tree/main/subpath

   • Correct ✅ https://github.com/owner/repo

2. Providing the wrong or no branch name

   • Check that you have provided the correct branch name

   • Check that the git repository URL is correct

Merge conflicts

Merge errors are usually mitigated by Automatic Merging Behavior, however unresolvable conflicts can occur if a link author force pushes changes to a repository, or a link consumer performs a merge commit. See Case 6 in Automatic Merging Behavior for the Backup and resync solution for this particular merge error.

Consult the Content git repository best practices for general advice on avoiding issues.

Can I share content from a private repository?

Warning

Please do not include personal access tokens in the nbgitpuller link, e.g. using a GitHub repo URL of the form https://login:<TOKEN>@hostname/path.git, since this is logged on the Jupyter server. Anyone with access to the server can therefore see your private token.

If you would like to share content from a private GitHub repository, you can use git-credential-helpers to do so. This helper library lets git automatically create GitHub app installation tokens for interacting with private repos that have the GitHub app installed. Note that the steps below work for private GitHub repositories only.

Steps

1. Install git-credential-helpers together with nbgitpuller

2. Setup a GitHub app to allow read access to the private repository

   • Create an app under your GitHub organization

   • Give it a descriptive name (such as ‘nbgitpuller private repo access’) and description, as users will see this when installing this app to authorize access to the private repo

   • Disable webhooks (uncheck the ‘Active’ checkbox under ‘Webhooks’). All other textboxes can be left empty.

   • Under ‘Repository permissions’, select ‘Read’ for ‘Contents’.

   • Under ‘Where can this GitHub App be installed?’, select ‘Any account’. This will enable users to push to their own user repositories or other organization repositories, rather than just the app owner organization repos.

   • Create the application with the ‘Create GitHub app’ button.

   • Note for later the numeric ‘App ID’ from the app info page you should be redirected to.

   • Create a new private key for authentication with the Generate a private key button. This should download a private key file, that you should keep secure and configure in the next step.

3. For this to work across multiple user accounts, update the system (not your local) gitconfig file with the following

   [credential "https://github.com"]
   helper = !git-credential-github-app --app-key-file <path-to-your-app-rsa-key-file> --app-id <id-of-your-github-app>
   useHttpPath = true
   

   Note

   You must use the private key, not a client secret.

   • To configure helm chart values for Zero to JupyterHub clusters with the gitconfig file, see the documentation on singleuser extra files

     • We recommend setting mountPath: /etc/gitconfig and stringData with the contents of the gitconfig file above

     • However if the software image is using git from conda-forge, the file should be mounted in ${CONDA_PREFIX}/etc/gitconfig

     • You can also try using git config --system --list --show-origin in the software image to show where the system-wide git config file is located.

4. Install the GitHub app to the private repo

   • Go to the ‘Public page’ of the GitHub app created. This usually is of the form https://github.com/apps/<name-of-app>. You can find this in the information page of the app after you create it, under ‘Public link’

   • Install the app into the account or the organization the private repo lives in, and grant it access only to the repo that needs to be pulled.