Work with projects in a Git repository

To enable collaboration with external stakeholders or the data science community at large, you can import projects from a Git repository and push project assets to the external Git repository.

The Git integration provides a flexible source code management method to track, back up, and collaborate on a project with multiple users. Collaborators in Git and in IBM® Watson™ Studio can push their changes to the repository so that everyone has access to the changes.

Complete the following tasks to integrate with an external GitHub repository:

Complete the following tasks to collaborate on the project:

If you need to sync up your local copy with the remote repository, you can Reset your local copy of the project.

Prepare your repository

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

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
Zepplin notebooks (.json files) zepplin
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 interface.

Enable your account to access the Git repository

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

Before you can work with assets in a Git repository, you must enable your IBM Watson Studio account to access the Git repository by creating a personal access token and adding it to your IBM Watson Studio account.

To enable your account to access the Git repository:

  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
      Note: 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 personal access 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
      Note: You can select additional scopes, but repo is the minimum required scope.
    5. Click Generate token and copy the token that is generated.
    Bitbucket
    1. Go to https://bitbucket.org.
    2. Go to Bitbucket Settings and select App passwords.
    3. Click Create app password.
    4. On the Add app password page, select the Write or Admin under Repositories so that you can import assets from the repository and commit and push changes to the repository.
      Note: You can select other permissions, but Write or Admin permissions on the repository are required.
    5. Click Create and copy the token that is generated.
    Bitbucket Server
    1. Go to your Bitbucket Server deployment.
    2. See the Bitbucket Server documentation for information on generating personal access tokens.
  2. Add the personal access token to your IBM Watson Studio user account:
    1. Click your avatar and select Settings.
    2. Open the Integrations tab and click add token.
    3. Select the platform on which you generated the token.
    4. Paste the token that you copied into the Access Token field.
    5. If prompted, specify your Git Host URL and your username.
    6. Give the token a meaningful name and click Create.

Import a project from a Git repository

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

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

Git projects are managed externally; therefore, collaborators must be added to the project in the external repository and each user who wants to access the repository from IBM Watson Studio must import a copy of the project into IBM Watson Studio.

You can import both public and private repositories.

To create a project for a Git repository:

  1. Open the Projects page and click Add Project.
  2. Go to the From Git repository tab.
  3. Select the access token that is associated with the Git deployment where the repository exists.
  4. Enter the URL of the repository.
    Tip: To get the correctly formatted version of repository URL:
    • On GitHub, 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
    • On Bitbucket, click Clone. Ensure that the HTTPS option is selected. Then, copy the URL, which ends with .git
  5. By default, the project has the same name as your repository, but you can rename the project.

After you create the project, the assets from the repository are displayed in the project in IBM Watson Studio.

Add assets to the project in IBM Watson Studio

You can add assets to the project in IBM Watson Studio. 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 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 the remote repository before you connect to the repository. 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

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

Remember: Only admins or editors can push their changes to the remote repository. If you have view permissions on the project you can only commit changes to your local copy of the project.

To commit your changes to the local copy of the repository:

  1. From the Git Actions menu (Screen capture of the Git Actions icon), select Commit.
  2. Specify the files that you want to add with the commit and enter a commit message.
  3. Click Commit.
  5. Enter a commit message and then click Commit and push.
To push your changes to the remote repository:
  1. From the Git Actions menu (Screen capture of the Git Actions icon), select Push.

    If your local copy is behind the repository copy, you should pull the latest changes from the remote repository and merge the changes with your local copy before you push your changes to the remote repository.

  2. If you want to create a release from the project, enter a version tag for the release.
  3. Click Push.
Tip: You can see a list of the commit messages for a project by selecting Commit history from the Git Actions menu. From the Commit history page, you can add tags to a commit or revert to a specific commit.

Pull changes from a Git repository

If a collaborator adds or edits an asset on the remote Git repository, you must pull the change from the remote repository before it appears in your local copy of the project.

Important: Pulling changes from the remote repository can potentially overwrite your local changes.
Before you pull the changes from the remote repository, ensure that any changes you have locally are backed up. For example you can:
  • Commit the changes to the remote repository
  • Export a copy of the project.
To pull changes from the repository:
  1. From the Git Actions menu (Screen capture of the Git Actions icon), select Pull.
  2. If your local copy is ahead of the remote repository, you must merge your changes. For more information, see Merge changes in a Git repository.

Merge changes in a Git repository

If you pull changes from the remote repository that conflict with changes in your local copy, you must merge the changes in one of 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.

When you resolve the merge conflicts, stage the conflicted files in the Git status summary panel and click the Complete Merge button.

Manual resolution: Resolve locally
Resolve merge conflicts locally 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 IBM Watson Studio.
  4. In the Git conflict resolution summary panel, stage the conflicted files and click the Complete Merge button to overwrite the files.
Discard all changes and revert to a past commit (not recommended)
From the Git Actions menu ( Screen capture of the Git Actions icon), select Commit history and revert to a previous commit.

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

Reset your local copy of the project

If you make changes to the local copy of your project but decide that you don't want to keep the changes, you can reset your project by pulling the current version of the project from the remote 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 repository.

To reset your project:

  1. Go to the Projects page.
  2. From the actions menu for the project, select Reset.
  3. Click Reset project.