4.2 GitHub Notebooks

Oracle Machine Learning UI supports direct interaction of Oracle Machine Learning Notebooks with your external GitHub repositories. You can now directly import notebooks from your GitHub repositories.

Note:

You may encounter an error if you retrieve information too frequently. This is because both public and private GitHub repositories are subjected to specific request limits. While it is unlikely that you will exceed the private repository limit of 5,000 requests per hour, it is common to hit the public limit of 60 requests per hour. GitHub restricts the number of API requests to prevent abuse and denial-of-service attacks, and also to ensure that the API remains available to all users.

With GitHub integration, you can interact with your GitHub repositories in the following ways:

  • Create GitHub Credentials
    You must have separate credentials to connect to your GitHub repositories. The credential object with your GitHub credentials are stored in the Autonomous AI Database. To connect to your GitHub repositories that are marked private, you require credentials containing the necessary information such as name, email, personal access token and so on.
  • Clone and Access your GitHub Notebooks
    To clone and access your GitHub notebook in Oracle Machine Learning UI, you must import the notebook from your GitHub repository. When you import the notebook, it clones the notebook and makes it available both on the Notebooks listing page and GitHub Notebooks listing page in Oracle Machine Learning UI.
  • Edit and Sync your GitHub Notebook
    You can update remote changes in your notebooks and also upload local changes in the notebooks back to your GitHub repository using the Version Control options—Pull changes and Push & commit in OML notebook editor to synchronize the cloned notebook with your GitHub repository copy of the notebook.
  • Manage GitHub Notebooks
    This page lists all the notebooks that you have cloned from a remote GitHub repository.

Parent topic: OML Notebooks

4.2.1 Create GitHub Credentials

You must have separate credentials to connect to your GitHub repositories. The credential object with your GitHub credentials are stored in the Autonomous AI Database. To connect to your GitHub repositories that are marked private, you require credentials containing the necessary information such as name, email, personal access token and so on.

The GitHub Credential interface in Oracle Machine Learning UI is the interface where you create the credentials to connect to your GitHub repositories.

Note:

GitHub repositories that are public can be accessed without credentials.
A repository, also known as repo, is the fundamental element of GitHub. It is a storage space where you can keep all your project files, including code, images, and other resources, along with their revision history. Repositories are essential for organizing, managing, and collaborating on projects.
You can perform the following tasks on the GitHub Credentials page:
  • Create: Click Create to create GitHub credentials
  • Delete: Select a credential and click Delete. Deleting a credential also deletes the repository definition associated with the credential.

    Note:

    When you delete a credential, all notebooks associated with the credential are converted into regular Oracle Machine Learning notebooks. As the credential is deleted, you can longer access and edit the associated notebooks in the GitHub repository.
To create GitHub credentials:
  1. On the Oracle Machine Learning UI home page, click GitHub Credentials. Alternatively, you may click on the user profile drop-down menu, click GitHub and then click Credentials. This opens the GitHub Credentials page.
  2. On the GitHub Credentials page, click Create. The Create Credentials dialog opens.

    Figure 4-6 GitHub Credentials page


    Description of Figure 4-6 follows
    Description of "Figure 4-6 GitHub Credentials page"

  3. On the Create Credentials dialog, provide the following details:

    Figure 4-7 Create Credential dialog


    Description of Figure 4-7 follows
    Description of "Figure 4-7 Create Credential dialog"

    1. Name: This is a name to identify this credential.

      Note:

      The length of the name is limited to 64 characters only. The valid characters are alphanumeric, underscore and the dollar sign.
    2. Provider: This is the name of the external repository. Currently, only the GitHub repository is supported.
    3. Email: This is the email ID of the Git user that created the repository. The maximum limit is 128 characters.
    4. Token: This is the Personal Access Token, a secure method to authenticate with GitHub repository. You can generate it from your GitHub profile. See Generate Personal Access Token for details.
    5. Click Create.
    This completes the task of creating the credentials and takes you back to the GitHub Credentials page.

Parent topic: GitHub Notebooks

4.2.1.1 Generate Personal Access Token

A Personal Access Token (PAT) is an authentication token. It is a secure method used for user authentication.

To generate the Personal Access Token (PAT):
  1. Open your GitHub profile, scroll down and click Settings.
  2. On the left navigation of your GitHub Settings page, scroll down and click Developer Settings.

    Figure 4-8 Developer Settings on left navigation pane


    Description of Figure 4-8 follows
    Description of "Figure 4-8 Developer Settings on left navigation pane"

  3. On the left navigation of the Developer Settings page, expand Personal access tokens and click Tokens (classic).

    Figure 4-9 Github Developer Settings


    Description of Figure 4-9 follows
    Description of "Figure 4-9 Github Developer Settings"

  4. Click Generate new tokens and then click Generate new token (classic).
  5. On the New personal access token (classic) page, enter the following:
    • Note: Enter any note about the token.
    • Expiration Date: Click the down arrow and select an option about the validity of this token.
    • Scope: In this entire section, select repo.
  6. Click Generate token.
    The token is generated. Click the copy icon to copy the token and use it when creating the GitHub credentials in Oracle Machine Learning UI.

Parent topic: Create GitHub Credentials

4.2.2 Clone and Access your GitHub Notebooks

To clone and access your GitHub notebook in Oracle Machine Learning UI, you must import the notebook from your GitHub repository. When you import the notebook, it clones the notebook and makes it available both on the Notebooks listing page and GitHub Notebooks listing page in Oracle Machine Learning UI.

Prerequisites:
  • You must have your GitHub credentials created.
  • The notebooks to be cloned must reside in your GitHub repository.
To clone your GitHub notebook:
  1. Go to your Oracle Machine Learning Notebooks listing page and click Import. Here, you have two options—File and Git.
  2. Click Git. This opens the GitHub Checkout page.
  3. On the GitHub Checkout page, enter these details:

    Figure 4-11 GitHub Checkout page


    Description of Figure 4-11 follows
    Description of "Figure 4-11 GitHub Checkout page"

    1. Repository URL: Enter the URL of the GitHub repository you want to access. You have the following options to provide the GitHub repository URL:
      • Minimum valid URL: You can provide the GitHub URL containing only the repository name and the owner. For example, https://github.com/RepoOwner/RepoName. This loads the branches found in the remote repository.
      • Base URL and branch: Enter the GitHub repository URL along with the branch you want to clone. For example, https://github.com/RepoOwner/RepoName/tree/BranchName/ or https://github.com/RepoOwner/RepoName/blob/BranchName/. This automatically loads the Branches field. Select the Branch Name defined in the URL. and this will trigger the load of the directory structure found in the repository.
      • Base URL, branch and directory: You can also provide the GitHub URL containing one or several sub-directories in the remote repository. For example, https://github.com/RepoOwner/RepoName/tree/Branch/Dir/Di2r This loads the directory structure and pre-select the directory specified in the URL.
      • Complete file path: You can also enter the complete file path in the remote GitHub repository. For example, https://github.com/RepoOwner/RepoName/blob/Branch/Dir/file.dsnb. This loads the branches, directories and the file in the Selected notebooks field at the bottom of the dialog.
    2. Select a credential: Click the down arrow and select a credential. If you do not have a credential created, click the + icon to create one. See Create GitHub Credentials for more information.
    3. Branch: The drop-down menu displays the branches available in the remote GitHub repository based on the specified repository owner, repository name, and credential combination. Select a branch. The notebooks available in the branch are listed. You can also filter the notebooks you are looking for by typing in the notebook name in the Filter field.
    4. Select the notebooks you want to clone and click Add. The notebooks you selected are now listed in the Selected notebooks section.
    5. Click Checkout. This starts cloning all the GitHub notebooks you selected. Once completed, it displays the message "Notebooks successfully cloned". Click Open Notebook listing on the message box to go to the Notebooks listing page.
  4. You can access all your cloned GitHub notebooks from the Oracle Machine Learning Notebooks listing page or from the GitHub Notebooks listing page.

    Figure 4-12 GitHub Notebooks option on the User Profile menu and OML UI home page


    Description of Figure 4-12 follows
    Description of "Figure 4-12 GitHub Notebooks option on the User Profile menu and OML UI home page"

    • To access your GitHub Notebooks listing page, click on the user profile drop-down menu on the top-right corner of the Oracle Machine Learning UI home page. Click GitHub, and then click Notebooks.
    • Alternatively, you can access the GitHub Notebooks listing page by clicking GitHub Notebooks on the Oracle Machine Learning UI home page.
    On the GitHub Notebooks listing page, click on the cloned notebook name to open it in the editor.

    Figure 4-13 GitHub Notebooks listing page


    Description of Figure 4-13 follows
    Description of "Figure 4-13 GitHub Notebooks listing page"

  5. To access your cloned GitHub notebooks from your Oracle Machine Learning Notebooks listing page, click on the notebook with the giticon.

    Figure 4-14 OML Notebooks listing page


    Description of Figure 4-14 follows
    Description of "Figure 4-14 OML Notebooks listing page"

This completes the task of cloning and accessing your GitHub notebooks.

Parent topic: GitHub Notebooks

4.2.3 Edit and Sync your GitHub Notebook

You can update remote changes in your notebooks and also upload local changes in the notebooks back to your GitHub repository using the Version Control options—Pull changes and Push & commit in OML notebook editor to synchronize the cloned notebook with your GitHub repository copy of the notebook.

Prerequisites:
To edit and sync the changes in your GitHub notebook:
  1. After editing your notebook, click Version Control to commit the changes to the GitHub repository. The Version Control pane opens on the right.
  2. On the Version Control pane:

    Figure 4-15 Version Control in OML notebook editor


    Description of Figure 4-15 follows
    Description of "Figure 4-15 Version Control in OML notebook editor"

    Note:

    To use these features, you must have your credentials linked to the GitHub notebook. Otherwise, the operations will fail.
    • Click Commit & Push to save and commit the edits done to the local (cloned) copy of your notebook to the main branch of your Git repository. This opens the Commit and Push dialog. Evaluate the changes (highlighted in a different color), provide a comment and click Continue. Once the changes are committed, it displays the confirmation message: New commit <commit ID> created and pushed.
    • Click Pull changes to pull all changes in the notebook from your Git repository to your cloned copy in Oracle Machine Learning UI. Note the Git repository/branch name in the Current branch field. A confirmation dialog opens with the repository/branch name. Click Pull to confirm. Once complete, it displays the confirmation message: Notebook pulled from the <branch name>.
    • Click checkout to change the branch and pull all changes in the notebook from the updated branch to your cloned copy in Oracle Machine Learning UI. In the Current branch field, copy paste the name of the branch if you want to change the branch from the default main to another branch. Once complete, it displays the confirmation message: Current branch is set to <branch name>.

Parent topic: GitHub Notebooks

4.2.4 Manage GitHub Notebooks

This page lists all the notebooks that you have cloned from a remote GitHub repository.

When you clone a notebook from a GitHub repository, it creates a repository definition. It contains the URL, directory information, the notebook name and creation date. All these information are listed here along with the notebook. You can directly open any notebook listed here, and edit or delete them.

Figure 4-16 GitHub Notebooks page


Description of Figure 4-16 follows
Description of "Figure 4-16 GitHub Notebooks page"

  • Workspace: This is the name of the workspace where the project (in which the notebook is saved) is created.
  • Project: This is the name of the project in which the notebook is saved in Oracle Machine Learning UI.
  • Name: This is the name of the notebook. It is a clickable link. You can click on the name to open and edit it directly in the notebook editor.
  • Created: This is the date and time of creation and last edit of the notebook.
  • Created By: This is the name of the OML user.
  • Repository Name: This is the name of the GitHub repository.
  • Repository Owner: This is the name of the GitHub repository owner.
  • Repository Path: This is the file name of the notebook.
  • Credential Name: This is the name of the user credential
You can perform the following tasks:
  1. Edit: To update repository path or credentials, select a notebook and click Edit. The Update Repository dialog opens. You can perform the following information: , you can update the GitHub repository URI and choose a different credential.
    1. Update the URI of the GitHub notebook.
    2. Click the down arrow to choose a different user.
    3. Click the + icon to create a new GitHub credential.
  2. Open: To open a notebook, click on the notebook name. It opens the notebook directly on the Oracle Machine Learning Notebook editor.
  3. Delete: To delete any notebook, select the notebook and click Delete. This deletes the local (cloned) copy of your GitHub notebook.

Related Topics

Parent topic: GitHub Notebooks