> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 grants 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 are 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. For more information about auth token permissions, see [Configuring user access to external version control](https://anaconda.com/docs/data-science/latest/data-science-workflows/external-repo-user.md).

> [!TIP]
>
> Anaconda recommends that you collect the following information before you begin:
>
> * If necessary, the fully qualified domain name (FQDN) of your version control server.
> * The organization, team, or group name associated with your service account.
> * The username of the administrator for the organization, team, or group.
> * 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 Enterprise Server | 2.15 through 3.17.4 |
| GitHub Enterprise Cloud | github.com |
| Bitbucket Server/Data Center | 5.9.1 through 8.9.0 |
| Bitbucket Cloud | bitbucket.org |
| GitLab Self-Managed | 10.4.2 through 17.4 |
| GitLab Cloud | gitlab.com |

## GitHub

> [tab] GitHub Enterprise Server
>
> 1. Create a backup copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
>
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
>
> 3. Locate the `git:` section of the file.
>
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
>
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
>
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the GitHub service your organization uses. |
>    | `type` | Specifies the API version for accessing GitHub repositories.  GitHub uses `github-v3-api` |
>    | `url` | The URL of the version control server API.  For example: `https://your-domain.com/api/v3/` |
>    | `credential-url` | The hostname of the GitHub server used to manage user credentials.  For example: `https://your-domain.com/api/path/` |
>    | `organization` | The name of your GitHub organization. |
>    | `username` | Specifies a username for a GitHub account. This account *must have Owner permissions for your GitHub organization*. |
>    | `auth-token` | The personal access token associated with the `username` GitHub account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example Github Enterprise Server configuration
>    >
>    > ```yaml theme={null}
>    > git:
>    >    ## 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/
>    >    disable-tls-verification: false
>    >    repository: '{owner}-{id}'
>    >    organization: <GitHub_organization>
>    >    username: <admin_username>
>    >    auth-token: <username_token>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
>
> 7. Save your changes.
>
> 8. Delete and restart system pods by running the following command:
>
>    ```sh theme={null}
>    # Replace <NAMESPACE> with your Workbench cluster namespace
>    kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>    ```
>
> Once all pods have returned to a running state, users are prompted to add their personal access token after logging into the platform.

> [tab] GitHub Enterprise Cloud
>
> 1. Create a backup copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
>
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
>
> 3. Locate the `git:` section of the file.
>
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
>
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
>
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the GitHub service your organization uses. |
>    | `type` | Specifies the API version for accessing GitHub repositories.  GitHub uses `github-v3-api` |
>    | `url` | The URL of the version control server API.  GitHub Enterprise Cloud uses `https://api.github.com` |
>    | `credential-url` | The hostname of the GitHub server used to manage user credentials.  GitHub Enterprise Cloud uses `github.com` |
>    | `organization` | The name of your GitHub organization. |
>    | `username` | Specifies a username for a GitHub account. This account *must have Owner permissions for your GitHub organization*. |
>    | `auth-token` | The personal access token associated with the `username` GitHub account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example Github Enterprise Cloud configuration
>    >
>    > ```yaml theme={null}
>    > git:
>    >    ## 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_username>
>    >    auth-token: <username_token>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
>
> 7. Save your changes.
>
> 8. Restart system pods with the following command for changes to take effect:
>
>    ```sh theme={null}
>    # Replace <NAMESPACE> with your Workbench cluster namespace
>    kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>
>    ```
>
> 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.

## GitLab

> [tab] GitLab Enterprise (Self-Managed)
>
> 1. Create a backup copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
> 3. Locate the `git:` section of the file.
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the GitLab service your organization uses. |
>    | `type` | Specifies the API version for accessing GitLab repositories.  GitLab Enterprise (Self-Managed) uses `gitlab-v4-api` |
>    | `url` | The URL of the version control server API.  For example: `https://your-gitlab-domain.com` |
>    | `credential-url` | The hostname of the Bitbucket server used to manage user credentials.  For example: `https://your-gitlab-domain.com` |
>    | `organization` | The name of your GitLab group. |
>    | `username` | Specifies a username for a GitLab account. This account *must have Administrator permissions for your GitLab Server*. |
>    | `auth-token` | The personal access token associated with the `username` GitLab Administrator account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example GitLab Enterprise (Self-Managed) configuration
>    >
>    > ```yaml theme={null}
>    > git:
>    >    ## 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_username>
>    >    auth-token: <username_token>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
> 7. Save your changes.
> 8. Restart system pods with the following command for changes to take effect:
>
>    ```sh theme={null}
>     # Replace <NAMESPACE> with your Workbench cluster namespace
>     kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>    ```
>
> 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.

> [tab] GitLab Enterprise (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 copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
>
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
>
> 3. Locate the `git:` section of the file.
>
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
>
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
>
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the GitLab service your organization uses. |
>    | `type` | Specifies the API version for accessing GitLab repositories.  GitLab Enterprise (Cloud) uses `gitlab-v4-api` |
>    | `url` | The URL of the version control server API.  GitLab (Cloud) uses `https://gitlab.com` |
>    | `credential-url` | The hostname of the GitLab server used to manage user credentials.  GitLab (Cloud) uses `https://gitlab.com` |
>    | `organization` | The name of your GitLab group. |
>    | `username` | Specifies a username for a GitLab account. This account *must have Administrator permissions for your GitLab instance*. |
>    | `auth-token` | The personal access token associated with the `username` GitLab Administrator account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example GitLab Enterprise Cloud configuration
>    >
>    > ```yaml theme={null}
>    > git:
>    >    ## 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_username>
>    >    auth-token: <username_token>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
>
> 7. Save your changes.
>
> 8. Restart system pods with the following command for changes to take effect:
>
>    ```sh theme={null}
>    # Replace <NAMESPACE> with your Workbench cluster namespace
>    kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>    ```
>
> 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

> [!WARNING]
>
> 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](https://confluence.atlassian.com/bitbucketserver/setting-a-system-wide-default-branch-name-1021220665.html) in Bitbucket to target `main`. If you do not, your deployments will fail.

> [tab] Bitbucket Server/Data Center
>
> 1. Create a backup copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
>
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
>
> 3. Locate the `git:` section of the file.
>
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
>
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
>
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the Bitbucket Server/Data Center service your organization uses. |
>    | `type` | Specifies the API version for accessing Bitbucket repositories.  Bitbucket Server/Data Center uses `bitbutcket-v1-api` |
>    | `url` | The URL of the version control server API.  For example: `https://your-bitbucket-server-domain:7990` |
>    | `credential-url` | The hostname of the Bitbucket server used to manage user credentials.  For example: `https://your-bitbucket-server-domain:7990` |
>    | `organization` | The name of your Bitbucket team. |
>    | `username` | Specifies a username for a Bitbucket account. This account *must have Admin level permissions for your Bitbucket Server*. |
>    | `auth-token` | The password associated with the `username` Bitbucket account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example Bitbucket Server/Data Center configuration
>    >
>    > ```
>    > git:
>    >    ## 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: <Bitbucket_admin>
>    >    auth-token: <admin_password>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
>
> 7. Save your changes.
>
> 8. Restart system pods with the following command for changes to take effect:
>
>    ```
>    # Replace <NAMESPACE> with your Workbench cluster namespace
>    kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>    ```
>
> 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.

> [tab] 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 copy of the `anaconda-enterprise-anaconda-platform.yml` configmap.
>
> 2. Open the `anaconda-enterprise-anaconda-platform.yml` configmap for editing.
>
> 3. Locate the `git:` section of the file.
>
> 4. *Uncomment* (remove the `#` from the start of lines in) the `Example external repo configuration` section.
>
> 5. *Comment out* (add a `#` to the start of) the remaining lines in the `git:` section.
>
> 6. Configure the `Example external repo configuration` values as follows:
>
>    | Attribute | Description |
>    | :- | :- |
>    | `name` | A descriptive name for the Bitbucket Server/Data Center service your organization uses. |
>    | `type` | Specifies the API version for accessing Bitbucket repositories.  Bitbucket cloud uses `bitbutcket-v2-api` |
>    | `url` | The URL of the version control server API.  Bitbucket cloud uses `https://api.bitbucket.org` |
>    | `credential-url` | The hostname of the Bitbucket server used to manage user credentials.  Bitbucket cloud uses `https://bitbucket.org` |
>    | `organization` | The name of your Bitbucket team. |
>    | `username` | Specifies a username for a Bitbucket account. *This account must have Admin-level permissions for your Bitbucket Server*. |
>    | `auth-token` | The password associated with the `username` Bitbucket account. |
>
>    > [!WARNING]
>    >
>    > The `url` and `credential-url` attributes *must* contain all lowercase characters.
>
>    > [accordion] Example Bitbucket Cloud configuration
>    >
>    > ```
>    > git:
>    >    ## 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: <Bitbucket_admin>
>    >    auth-token: <admin_password>
>    >    # type: internal
>    >    # http-timeout: 60
>    >    # repository: '{owner}-{id}'
>    >    # The maximum size of a commit in the git repository max-commit-file-size: 50000000
>    > ```
>
> 7. Save your changes.
>
> 8. Restart system pods with the following command for changes to take effect:
>
>    ```
>    # Replace <NAMESPACE> with your Workbench cluster namespace
>    kubectl delete -n <NAMESPACE> --wait=false $(kubectl get pods -o name|grep ap-)
>    ```
>
> 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.