Git repositories in Domino

Overview 

Domino supports adding Git repositories to projects. Repositories that have been added to a project are available to runs and workspace sessions in that project, allowing you to access the contents of those repositories just as you would your Domino files. This article explains how you can add a Git repository to a project, access the added repository from within a workspace, and commit any changes back to the repository.

Domino supports connecting to Git servers via HTTPS and SSH, and both public and private repositories.

 

Add credentials

If you are adding a private repository, want to write commits to remote, or are using SSH, you will need to add Git credentials to your Domino account. Domino will use these credentials to authenticate with the service hosting your repository when you start a run or workspace session. Domino supports two types of credentials: Personal Access Tokens and SSH Private Keys.

Personal Access Tokens

You will need a Personal Access Token to access a private repository via HTTPS. If the URI you want to use to interact with a repository is formatted as https://<domain>/<user>/<repository>.git, you will need a Personal Access Token. Personal Access Tokens are supported by the following Git services. Click on each to see documentation.

NOTE

Bitbucket's implementation of HTTPS access is currently not supported by Domino. To connect to Bitbucket repositories with Domino, use SSH.

The Personal Access Token you generate needs to have read and write access to your private repositories. After generating a Personal Access Token in your Git service, use these steps to add it to Domino:

  1. In Domino, click your username in the upper right, then click Account Settings.
  2. Scroll down to the panel labeled Git Credentials, then click Add a New Credential.
  3. In the Domain field, enter the domain of the service hosting your repository, e.g. github.com or gitlab.com.
  4. For Authentication Credential Type, click to select Personal Access Token.
  5. Enter your Personal Access Token, then click Add Credential.
  6. You should now see your credential listed in the Git Credentials panel. You can also delete it from this panel if desired.

    git-credentials-panel-https.png

SSH Private Keys

You will need an SSH Private Key to access a repository via SSH. If the URI you want to use to interact with a repository is formatted as <user>@<domain>:<username>/<repository>.git, you will need an SSH Private Key. SSH access is supported by the following Git services. Click on each to see documentation.

After setting up SSH access with your Git service, you should have both a public key that you provided to the Git service, and a private key. Use these steps to add the private key to Domino:

  1. In Domino, click your username in the upper right, then click Account Settings.
  2. Scroll down to the panel labeled Git Credentials, then click Add a New Credential.
  3. In the Domain field, enter the domain of the service hosting your repository, e.g. github.com or gitlab.com.
  4. For Authentication Credential Type, click to select Private SSH Key.
  5. Paste in your private key. This will be the contents of the private key file that matches the public key you provided to your Git service.
  6. If you set up your SSH keys to require a passphrase when used, enter it in the Passphrase field, then click Add Credential.
  7. You should now see your credential listed in the Git Credentials panel. You can also delete it from this panel if desired.

    git-credentials-panel-ssh.png

 

Add a repository to a project

  1. Open the project you want to add a repository to, then click Files from the left navigation bar.
  2. Click to open the Git Repositories tab, then click Add a New Repository.

    git-repo-tab.png

  3. Enter an optional directory name and the HTTPS or SSH URI of the repository you want to add. The directory name will be the directory in /repos that this repository clones into. It defaults to the name of the repository.
  4. Use the dropdown menu to choose which branch of the repository you want Domino to check out when it clones this repository into a run or workspace. If you leave this setting at Use default branch, Domino will check out the branch specified as default by your Git service, typically master. You can also specify a different branch name, tag name, commit ID, or supply a custom Git ref.

    add-repo-modal.png

  5. Click Add Repository.

 

Working with a Git repository in Domino

NOTE: The instructions below on committing back to Git repositories are only applicable to Domino 2.5.2+. Previous versions do not support committing to these repositories through the Domino UI.

When you start a run or workspace in a project, any repositories added to the project are cloned into /repos and will have the branch or commit you specified checked out. Remember that your Domino files are in /mnt, which is a sibling of /repos. Both directories are in the filesystem root (/). Scripts you have added as Domino files can interact with the contents of these repositories by specifying an absolute path to /repos/<repo-name>/<file>.

Git interaction in the workspace UI

When you start a workspace in a project that has added Git repositories, you will see those repositories listed in the Session Overview under Git repos. If you make changes to the contents of those repositories while running the workspace, those changes will be itemized file-by-file under each repository. If you want to commit those changes back to the repository, click the checkbox next to the repository name and then click Full Sync.

session-overview-git-repos.png

You will be prompted to supply a commit message. This commit message will be attached to commits to the selected Git repositories, and to a new revision of the Domino project if there are changes to Domino files. Git commits will be pushed to the default branch you specified when adding the repository.

commit-to-repos-modal.png

If you attempt to stop your workspace while there are uncommitted changes to your Git repositories, you will be prompted to commit those changes. This works the same as the Session Overview interface. Click the checkbox next to the repositories you want to commit to, supply a commit message, and click Stop and Commit.

stop-workspace-commit-prompt.png

NOTE: If you try to commit when there are conflicts between your local changes and the state of the default branch in remote, Domino will create a new branch from its local state. Domino will then push that new branch to remote. After this happens, you will need to resolve those conflicts outside of Domino, or use the command line in your workspace to resolve them. The next time you open a workspace, Domino will check out the default branch from remote, not the new branch it pushed.

Git interaction from the workspace command line

Both Jupyter and RStudio workspaces have command line tools. You can use these to interact with your repositories with conventional Git commands. Navigate to /repos in your command line to find your project’s repositories. Visit the official Git documentation to learn more about using Git on the command line.

To open the RStudio command line, click Tools -> Shell…

open-rstudio-shell.png

To open the Jupyter command line, from the Files tab click New -> Terminal

open-jupyter-terminal.png

 

Keywords: Git, GitHub, GitLab, Bitbucket, credentials, integration, connect

 

Was this article helpful?
0 out of 0 found this helpful