GitHub Version Control for Jupyter Notebooks¶

To use the version control for Jupyter Notebooks using GitHub, you must perform the following tasks:

  1. Configure Version Control Settings
  2. Configure a GitHub Token
  3. Link Jupyter Notebooks to GitHub

After configuring the GitHub repository, you can perform the following tasks to manage the notebook versions:

  • Pushing Commits to GitHub
  • Viewing and Comparing the Jupyter Notebook Versions
  • Restoring a Commit from GitHub
  • Creating a Pull Request from Jupyter Notebooks
  • Resolving Conflicts While Using GitHub

Configuring a GitHub Token¶

You can configure a GitHub Token for Jupyter notebooks at per user and per account setting level from the My Accounts or JupyterLab interface.

  • To configure the GitHub token for Jupyter notebooks for your account, see Configuring a GitHub Token.

  • To configure the GitHub token from the Jupyter notebooks, perform the following steps:

    1. Navigate to Notebooks >> Jupyter and open a Jupyter notebook.

    2. From the left sidebar, click on the Github Versions icon as shown in the following figure.

      ../../../../../_images/ConfigGitHubinNote-jupy.png

    3. Click Configure now.

    4. In the dialog box add the generated GitHub token and click Save.

      The GitHub token is now configured for your account.

Linking Jupyter Notebooks to GitHub¶

After configuring the GitHub token, you can link the Jupyter notebooks to GitHub.

  1. Obtain the GitHub repository URL.

    1. Navigate to the GitHub profile and click Repositories.

    2. From the list of repositories, click the repository that you want to link.

    3. Copy the URL that is displayed within that repository.

      Alternatively, you can navigate to the GitHub profile and copy the URL from the browser's address-bar.

      Note

      If you want to add HTTPS *.git link as the GitHub repository URL, click Clone or Download. A drop-down text box is displayed. Copy the HTTPS URL or click Use HTTP (if it exists) to copy the HTTP URL.

  2. Navigate to Notebooks >> Jupyter and open a Jupyter notebook.

  3. From the left sidebar, click on the GitHub Versions icon as shown in the following figure.

    ../../../../../_images/link-github-jp.png

  4. Click the Link Now option.

  5. In the Link Notebook to GitHub dialog box, perform the following actions:

    1. Add the GitHub repository URL in the Repository Web URL text field. Ensure that the GitHub profile token has read permissions for the repository to checkout a commit and write permissions for the repository to push a commit.

    2. Select a branch from the Branch drop-down list.

    3. Add an object path file in the Object Path text field.

    4. If you want to strip the outputs from the notebooks before committing to GitHub, select the Strip Output checkbox.

      A sample is as shown in the following figure.

      ../../../../../_images/link-github-config-jp.png

    5. Click Save.

Pushing Commits to GitHub¶

After you link notebooks with a GitHub profile, you can start using the notebook to push commits to the GitHub directly from a notebook.

Steps¶

  1. Open the required Jupyter notebook and save the changes.
  2. From the left sidebar, click on the GitHub Versions icon.
  3. Click the Push icon to commit. A dialog opens to push commits.
  4. Add a commit message and click Save to push the commit to the GitHub repository. You can use the option force commit to force push over the old commit (irrespective of any conflict).

Note

Qubole does not store commits or revisions of notebooks. However, commits or revisions of notebooks can be fetched from users' GitHub account whenever required.

Viewing and Comparing the Jupyter Notebook Versions¶

You can view a particular version of the Jupyter notebook by using the View option in the GITHUB VERSIONS sidebar as shown below.

../../../../../_images/view-in-github.png

You can compare a version of the Jupyter notebook with the previous version or version with current changes by using the Compare option in the GITHUB VERSIONS sidebar as shown below.

The Compare icon on top of the left sidebar compares the current notebook with the head of the branch. The Compare hyperlink in the left sidebar compares the given version with the previous version.

The following image shows a sample comparison of Jupyter notebook versions.

../../../../../_images/compare-in-github.png

Restoring a Commit from GitHub¶

  1. Open the required Jupyter notebook.
  2. From the left sidebar, click on the GitHub Versions icon.
  3. Select a version from the list and click Restore to checkout that version.
  4. Click OK to checkout that version in the confirmation dialog box.

Note

Qubole does not store commits or revisions of notebooks. However, commits or revisions of notebooks can be fetched from users' GitHub account whenever required.

Creating a Pull Request from Jupyter Notebooks¶

  1. Open the required Jupyter notebook.

  2. From the left side bar, click on the GitHub Versions icon.

  3. Click on the Gear icon in the GITHUB VERSIONS pane. The Link Notebook to GitHub dialog is displayed.

  4. Click on the Create PR hyperlink.

  5. Proceed with the steps in GitHub to create the PR.

    For more information, see GitHub Documentation.

Resolving Conflicts While Using GitHub¶

There may be conflicts while pushing/checking out commits in the GitHub versions.

Note

You can use the option force commit to force push over the old commit (irrespective of any conflict).

Perform the following steps to resolve conflicts in commits:

  1. Clone the notebook.
  2. Link the cloned notebook to the same GitHub repo branch and path as the original notebook.
  3. Checkout the latest version of the cloned notebook.
  4. Manually port changes from the original notebook to the cloned notebook.
  5. You can commit the cloned notebook after porting changes.