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.

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 credentials are created and securely 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 Notebook
  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.

4.2.1 Create GitHub Credentials

You must have separate credentials to connect to your GitHub repositories. The credentials are created and securely 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.

   Figure 4-5 Home page

   
   

   
   Description of "Figure 4-5 Home 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 GitHub Credentials page"

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

   Figure 4-7 Create Credential dialog

   
   

   
   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.

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

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

4.2.2 Clone and Access your GitHub Notebook

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.

   Figure 4-10 Import options

   
   

   
   Description of "Figure 4-10 Import options"

   
   
2. Click Git. This opens the Git Clone dialog.
3. On the Git Clone dialog, enter these details:

   Figure 4-11 Git Clone dialog

   
   

   
   Description of "Figure 4-11 Git Clone dialog"

   
   
   1. Enter a valid GitHub URI: Paste the URL of the GitHub notebook you want to import.

      Note:

      Copy and paste the URL of your GitHub notebook here.
   2. Select a credential: Click the down arrow to 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. Click OK. This starts cloning your GitHub notebook. Once completed, it opens the notebook in the Notebook editor.
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 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 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 icon.

   Figure 4-14 OML Notebooks listing page

   
   

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

   
   

This completes the task of cloning and accessing your 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:

• Import the notebook from the GitHub repository. For more information, see Clone and Access your GitHub Notebook
• Open the notebook:
  • Either from the GitHub Notebooks listing page. See Manage GitHub Notebooks
  • Or, from the Oracle Machine Learning Notebooks listing page. See Access your Oracle Machine Learning Notebooks.

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

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