Git repository projects

To collaborate with external stakeholders and the data science community at large, you can import projects from a Git repository and push project assets and changes to a Git repository from Watson Studio Local.

The Git integration feature provides a flexible source code management method to track, back up, and collaborate on a project with multiple users. Collaborators in Git and in Watson Studio Local can import assets from shared repositories and contribute their own assets and changes to the project so that everyone has access to the changes.

You can import, push, and pull changes from Git repositories with Watson Studio Local. All assets in the project will be on the Git repository when you push the changes.

Files that are not under one of these folders will be shown under Other Files on Watson Studio Local.

Do the following tasks to set up integration with an external Git repository:

  1. Prepare your repository
  2. Enable your account to access the Git repository
  3. Import a project from a Git repository

You can do the following tasks when you collaborate on a Git repository project:

If you are using an external Git server, you will need to allow network traffic between the compute nodes on your Watson Studio Local cluster and your Git server. Check with your Git server provider to learn the specific ports that are used by your Git server.

Prepare your repository

Some files need to be in a specific repository folder to display and behave appropriately in Watson Studio Local.

If you pre-populate the repository, ensure that your repository includes the following folders for each type of asset:

Asset type Folder name
Jupyter notebooks (.ipynb files) jupyter
Zeppelin notebooks (.json files) zeppelin
RStudio assets rstudio
Data sets datasets
Models models

Files that are not under one of these folders are displayed in the Other Files list in the project assets.

Enable your account to access the Git repository

Important: Each user who wants to access the Git repository from Watson Studio Local must complete this task.

Before you can import and push assets on a Git repository, you must enable your Watson Studio Local user account to access the Git repository. You enable access by creating a personal access token with the required access scope in the Git repository and linking the token to your Watson Studio Local account.

To create a personal access token:

  1. Generate your personal access token for the version of Git where the repository exists:
    Version Instructions
    GitHub
    1. Go to https://github.com/settings/tokens.
    2. Click Generate a personal access token.
    3. On the New personal access token page, select the repo scope so that you can import assets from the repository and commit and push changes to the repository.Screen shot of the repo option on the New personal access token page

      You can select additional scopes, but repo is the minimum required scope.

    4. Click Generate token and copy the token that is generated.
    GitHub Enterprise
    1. Go to your GitHub Enterprise deployment.
    2. Go to Settings and then select Developer settings > Personal access tokens
    3. Click Generate a token.
    4. On the New personal access token page, select the repo scope so that you can import assets from the repository and commit and push changes to the repository.Screen shot of the repo option on the New personal access token page

      You can add additional scopes, but repo is the minimum required scope.

    5. Click Generate token and copy the token that is generated.
    BitBucket
    1. Go to your BitBucket home page.
    2. Click your personal avatar on the bottom left and click Bitbucket settings. Then select Access Management > App passwords
    3. Click Create app password.
    4. On the Add app password page, select the Projects and Repository scope so that you can import assets from the repository and commit and push changes to the repository.

      You can add additional scopes, but write access to projects and repository is the minimum required scope.

    5. Click Create and copy the password that is generated.
    BitBucket Server
    1. Go to your BitBucket Server home page.
    2. In the right corner of the page, click your avatar and click View Profile.
    3. Click on Manage Account.
    4. On the left, click Personal access tokens. Then, on the right side of the page, click Create a token.
    5. Enter your token details, such as Token name. Select at least the write permission for the Projects and Repository, and make sure to restrict these to only the level needed.

      You have now generated a personal access token.

    6. Copy the token address and click Continue.
  2. In Watson Studio Local, add your personal access token:
    1. Open your profile settings, select the Git Integrations tab, and click Add token.
      Add token
    2. Fill out the fields as required, and be sure to paste the token that you copied into the Access token field and to give the token a name.
      Tip: If a Git Host URL is required, be sure you get the correctly formatted version of the repository URL. From the repository, click Clone or download. Ensure that the dialog is called Clone with HTTPS. If it is not, click Use HTTPS. Then, copy the URL, which ends with .git
    3. Click Create.

You can add more access tokens later by following these same steps.

Import a project from a Git repository

Important: Each user who wants to access the Git repository from Watson Studio Local must complete this task.

After you save the access token to your user account, you must create a project in Watson Studio Local for the Git repository.

Git projects are managed in Git; therefore, collaborators must be added to the project in Git, and each user who wants to access the repository from in Watson Studio Local must import a copy of the project into in Watson Studio Local. You can import both public and private repositories.

To link a project to an existing Git repository, you must have administrator permission to the project. All users must have permission to access the Git repository. Granting user permissions to repositories must be done in the Git repository.

To create a project from an existing Git repository:

  1. From your projects list, click to add a new project. On the Create Project page, select the From Git repository tab.
  2. In the Token field, select the access token that is associated with the Git deployment where the repository exists. If there are none, a new token must be created. See the section Enable your account to access the Git repository for more details.
    Select token
  3. Specify the required information and complete the steps to add the project. If you want to change the name of the project, specify it in the Project Name field. By default, the project name is the repository name.
    Tip: If a Git Host URL is required, be sure you get the correctly formatted version of the repository URL. From the repository, click Clone or download. Ensure that the dialog is called Clone with HTTPS. If it is not, click Use HTTPS. Then, copy the URL, which ends with .git

Now you can view the project and all its imported assets like any other project in Watson Studio Local in your project list.

Add assets to a Git repository

You can add assets to a Git-linked project. However, when you add an asset to the project, your changes remain in your local copy of the repository until you commit and push the changes to the remote Git repository.

Each type of asset is added to a specific folder in the repository:

Asset type Folder name
Jupyter notebooks (.ipynb files) jupyter
Zepplin notebooks (.json files) zepplin
RStudio assets rstudio
Data sets datasets
Models models
Remember: It is strongly recommended that you create these folders in Git before you connect to the repository from Watson Studio Local. However, any folders that do not exist on the repository are automatically created when you commit and push your first change to the repository.

Commit and push changes to a Git repository project

Any assets you add to the project remain in your local copy of the project until you commit and push the changes to the remote Git repository.

To commit changes to the repository:

  1. From the project page, select the Git Actions icon ( Git Actions) in the project action bar and click Commit.
  2. Select which files to commit, and type a message about the committed changes then click Commit.

    Commit

    Tip:
    • Empty directories do not show up in the file list. To commit and push an empty directory, create a .keep file under it
    • You can view the commit messages by navigating to /user-home/{uid}/DSX_Projects/{projectName} and running git log.

Only an Editor or Admin in the project can push changes. To push committed project changes:

  1. Select the Git Actions icon ( Git Actions) in the project action bar and click Push. If your local copy is behind the repository copy, a message will advise that you pull changes first.

    Push

  2. Type a version tag for the release. This field is required to create a release from this project at a later time.
  3. Click Push.

From the Git Actions icon ( Git Actions) in the project action bar, you can click Commit history for a history of Git commits and who performed them. You can also add multiple tags to each commit, or revert to a specific commit.

Commit history

Pull changes for a Git repository project

You can update your assets on a Watson Studio Local project by pulling changes from its linked Git repository.

Make sure your project is already backed up in some way, such as exporting it as a .zip file or committing it on Git before pulling from a repository.
Important: The process of accepting changes could potentially overwrite changes you recently made in Watson Studio Local.

To pull changes from a repository, select the Git Actions icon ( Git Actions) in the project action bar and click Pull.

Merge changes for a Git repository project

Merge conflict

Whenever you pull changes and Watson Studio Local detects a Git merge conflict, you can resolve it in the following ways:

Automatic resolution: Strategy: theirs
Rerun the Git pull but automatically drop your local changes in a merge conflict.
Automatic resolution: Strategy: ours
Rerun the Git pull but automatically drop the remote changes in a merge conflict.
Manual resolution: Open terminal
Open a web terminal in a new page so you can resolve the merge conflicts by command line, for example, using git, vi, or windiff.

Open terminal

When finished, stage the conflicted files in the Git status summary panel and click Complete Merge.
Manual resolution: Resolve locally
Resolve merge conflicts locally by using your own merge conflict solution:
  1. Export the project as a ZIP file to your local machine.
  2. Use your own tools such as Eclipse to resolve the conflicts.
  3. Drag the finished project into the Replace project page to upload it back into Watson Studio Local.
  4. In the Git conflict resolution summary panel, stage the conflicted files and click Complete Merge to overwrite the files.
Discard all changes and revert to a past commit (not recommended)
From the Git Actions icon ( Git Actions) in the project action bar, click Commit history and revert to a previous commit.

Until you resolve the merge conflicts, your project will wait in merge state.

Want to see Git merge conflict resolution in action? Watch this short video:
Figure 1. Video that shows Git merge conflict resolution in Watson Studio Local.

Reset your Git repository project

If you make changes to the local copy of your project but decide that you don't want to keep them, you can reset your project by pulling the current version of the project from the remote Git repository.

Resetting your local copy also enables you to sync up with other collaborators in the project.

Important: When you reset your copy of the project, all of the assets in the project are overwritten with the versions of the assets that are in the remote Git repository.

To reset your project, select the Git Actions icon beside the project in your project list and click Reset.

This action will reset your project to whatever is in the master repository.