Connecting to an external version control repository#

Data Science & AI Workbench supports the use of an external version control repository for user-created projects. Anaconda recommends connecting to this external version control repository at time of installation, however you are also able to migrate from one version control repository to another after installation is complete.

  • To provide permission granularity and maintain parity with your external version control repository, Workbench will grant individual platform users access to individual repositories. To prevent default permissions being applied to all users within a group, users cannot belong to the given organization or group.

  • Platform users will be prompted for their access token before they create their first project in Workbench. Anaconda recommends you advise users to create an ever-lasting token, to retain permanent access to their files from within Workbench. The specific auth token permissions required for each repository are outlined here.

Make sure you have the following prerequisites before you begin:

  • The fully qualified domain name (FQDN) of your versions control server.

  • The organization, team or group name associated with your service account.

  • The username of the Administrator for the organization, team or group. This user will require full Admin permissions.

  • The personal access token or password required to connect to your version control repository.

Supported external git versions#

Workbench supports integration with the following external repositories:

External repository

Supported versions

GitHub Server

2.15, through 3.4.1

GitHub Cloud

github.com

Bitbucket Server/DC

5.9.1 through 7.21.0

Bitbucket Cloud

bitbucket.org

GitLab Self-Managed

10.4.2 through 14.9.2

GitLab Cloud

gitlab.com

Github Enterprise Edition (Server)#

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

name = A descriptive name for the service your organization uses.

type = The type of version control repository your organization uses: github-v3-api.

url = The URL of the API https://<FQDN>.com/api/v3/.

credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://<FQDN>.com/api/v3/.

repository = Must be '{owner}-{id}' encased in single quotes.

organization = The name of your Github organization.

username = The username associated with the Administrator account This account must have full Admin permissions.

auth-token = The personal access token for the Administrator account associated with the username.

EXAMPLE:

git:
  default:
    ## Example external repo configuration
    name: github-server
    type: github-v3-api
    url: https://<FQDN>/api/v3/
    http-timeout: 60
    credential-url: https://<FQDN>/api/v3/
    repository: '{owner}-{id}'
    organization: <github organization>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  1. Save your changes.

  2. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their personal access token after logging into the platform.

Github Enterprise Edition (Cloud)#

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

name = A descriptive name for the service your organization uses.

type = The type of version control repository your organization uses: github-v3-api.

url = The URL of the API https://api.github.com/.

credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://github.com/<github-organization>.

repository = Must be '{owner}-{id}' encased in single quotes.

organization = The name of your Github organization.

username = The username associated with the Administrator account This account must have full Admin permissions.

auth-token = The personal access token for the Administrator account associated with the username.

EXAMPLE:

git:
  default:
    ## Example external repo configuration
    name: github-cloud
    type: github-v3-api
    url: https://api.github.com/
    http-timeout: 60
    credential-url: https://github.com/<github-organization>
    repository: '{owner}-{id}'
    organization: <github organization>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  1. Save your changes.

  2. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their personal access token after logging into the platform.

Bitbucket Server/Data Center#

Caution

By default, Bitbucket uses master as its default Git branch. Workbench uses main as its default Git branch. You must update the system-wide default branch name in Bitbucket to target main. If you do not, your deployments will fail.

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

name = A descriptive name for the service your organization uses.

type = The type of version control repository your organization uses: bitbucket-v1-api.

url = The URL of the API https://<FQDN>:7990.

credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://<FQDN>:7990.

repository = Must be '{owner}-{id}' encased in single quotes.

organization = The name of your Bitbucket team.

username = The username associated with the Administrator account This account must have full Admin permissions.

auth-token = The Bitbucket app password for the Administrator account associated with the username.

EXAMPLE:

git:
  default:
    ## Example external repo configuration
    name: bitbucket-server
    type: bitbucket-v1-api
    url: https://<FQDN>:7990
    http-timeout: 60
    credential-url: https://<FQDN>:7990
    repository: '{owner}-{id}'
    organization: <bitbucket team>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  1. Save your changes.

  2. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their app password after logging into the platform.

Bitbucket Cloud#

Note

Bitbucket.com does not support versioning of archive downloads and app deployments. In other words, the latest revision will always be downloaded or deployed.

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

    name = A descriptive name for the service your organization uses.

    type = The type of version control repository your organization uses: bitbucket-v2-api.

    url = The URL of the API https://api.bitbucket.org.

    credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://bitbucket.org.

    repository = Must be '{owner}-{id}' encased in single quotes.

    organization = The name of your Bitbucket team.

    username = The username associated with the Administrator account This account must have full Admin permissions.

    auth-token = The Bitbucket app password for the Administrator account associated with the username.

    EXAMPLE:

    git:
  default:
    ## Example external repo configuration
    name: bitbucket-cloud
    type: bitbucket-v2-api
    url: https://api.bitbucket.org
    http-timeout: 60
    credential-url: https://bitbucket.org/
    repository: '{owner}-{id}'
    organization: <bitbucket team>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  7. Save your changes.

  8. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their app password after logging into the platform.

Gitlab Enterprise Edition (Self-Managed)#

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

    name = A descriptive name for the service your organization uses.

    type = The type of version control repository your organization uses: gitlab-v4-api.

    url = The URL of the API https://<FQDN>.com.

    credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://<FQDN>.com.

    repository = Must be '{owner}-{id}' encased in single quotes.

    organization = The name of your GitLab group.

    username = The username associated with the Administrator account This account must have full Admin permissions.

    auth-token = The access token for the Administrator account associated with the username.

    EXAMPLE:

    git:
  efault:
    ## Example external repo configuration
    name: gitlab-server
    type: gitlab-v4-api
    url: https://<FQDN>.com
    http-timeout: 60
    credential-url: https://<FQDN>.com
    repository: '{owner}-{id}'
    organization: <gitlab group>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  7. Save your changes.

  8. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their access token after logging into the platform.

Gitlab Enterprise Edition (Cloud)#

Note

GitLab.com does not support versioning of archive downloads and app deployments. In other words, the latest revision will always be downloaded or deployed.

  1. Create a backup of the anaconda-enterprise-anaconda-platform.yml ConfigMap.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap for editing.

  3. Locate the git section (pictured below)

  4. Uncomment the Example external repo configuration section.

  5. Comment the Internal repo configuration section.

  6. Configure the Example external repo configuration.

    name = A descriptive name for the service your organization uses.

    type = The type of version control repository your organization uses: gitlab-v4-api.

    url = The URL of the API https://gitlab.com.

    credential-url = The URL to authenticate against for repository operations such as cloning and pushing https://gitlab.com.

    repository = Must be '{owner}-{id}' encased in single quotes.

    organization = The name of your GitLab group.

    username = The username associated with the Administrator account This account must have full Admin permissions.

    auth-token = The access token for the Administrator account associated with the username.

    EXAMPLE:

    git:
  default:
    ## Example external repo configuration
    name: gitlab-cloud
    type: gitlab-v4-api
    url: https://gitlab.com
    http-timeout: 60
    credential-url: https://gitlab.com
    repository: '{owner}-{id}'
    organization: <gitlab group>
    username: <admin>
    auth-token: <token>

    ## Internal repo configuration
    #name: Example.com Workbench Server
    #type: internal
    #url: http://127.0.0.1:8088/
    #http-timeout: 60
    #username: anaconda

  7. Save your changes.

  8. Restart system pods with the following command for changes to take effect:

    kubectl get pods | grep ap- | cut -d' ' -f1 | xargs kubectl delete pods

Once all pods have returned to a running state, users should now be prompted to add their access token after logging into the platform.