# Configure GitHub integration > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/git-configuration # Configure GitHub integration > **NOTE:** The legacy GitHub REST APIs referenced here are tied to GitHub exclusively. The newer Git provider integration pattern provides more flexibility and control and should be utilized if you are starting out or having issues with the GitHub APIs. GitHub integration requires configuration within both ThoughtSpot, accomplished via the V2.0 REST APIs, and your Git provider (GitHub currently). ## Configure Git repository Before you begin, make sure you have a GitHub or GitHub Enterprise account and access to a repository. Ensure that your account has one of the following types of access tokens: - [Personal access token (Classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#personal-access-tokens-classic) Make sure the access token has the `repo` scope that grants full access to public and private repositories, commit and deployment status, repository invitations, and security events. - [Fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens). Make sure the token allows at least the following permissions: - `Metadata`: read - `Commit statuses`: read and write - `Contents`: read and write ### Create branches for ThoughtSpot 1. Create a **branch** for use as the ThoughtSpot **configuration branch**, with no branch protection rules 2. Create one branch in the Git repository for each environment, following the patterns described in [Recommended configuration]({{navprefix}}/{{version_control}}#_recommended_configuration_and_best_practices). ## Enable Orgs and Git integration To configure Git branches and workflows, both Orgs and the Git integration feature must be enabled for your ThoughtSpot instances. To enable these features on an instance, contact ThoughtSpot Support. ## Confirm permissions within ThoughtSpot Orgs - To commit objects from ThoughtSpot to a Git repository, your ThoughtSpot user account requires at least view permission for all objects that will be committed as part of the operation. - To deploy or revert objects from a Git repository to ThoughtSpot, you require edit access to all objects that will be updated as part of the deployment. If the deployment contains Models, Views, or Tables, users require **Can manage data** (`DATAMANAGEMENT`) privilege for deploy, commit, and revert operations. ## GUID mapping and configuration files ThoughtSpot maintains a set of configuration files to facilitate the CI/CD process for developers. Typically, it includes: - One [GUID mapping file]({{navprefix}}/{{guid-mapping}}) per environment This file documents the GUID mapping for ThoughtSpot development objects from the source cluster, and their equivalent objects in the production environment to which commits are deployed. - One deploy file per environment This file tracks the last `commit_id` of the last successful deploy operation. These files should be configured to save to their own "configuration branch" in Git and do not need to be merged into any other branches. You can [automate the initialization]({{navprefix}}/{{git-configuration}}#initialize-mapping) of these files using the REST API. ## Connect your ThoughtSpot environment to the Git repository Each Org within a ThoughtSpot instance can be configured with its own Git configuration. To connect your ThoughtSpot instance to a Git repository using REST API, send a `POST` request with the following parameters to the `/api/rest/2.0/vcs/git/config/create` REST API v2.0 endpoint. Updates can be sent via `[/vcs/git/config/update]({{navprefix}}/{{git-configuration}}#update-git-config)`, whereas using the `/create` endpoint again will serve to completely overwrite the existing configuration. ### Configuration options The simplest deployment pattern enables **one Git branch** using the `branch_names` parameter, with the same branch as the `commit_branch_name`. The `configuration_branch_name` should be the same for all Orgs related to the same project. This will centralize all the [commit and GUID mapping files]({{navprefix}}/{{git-configuration}}#guid-map-and-config-files) for all environments into one branch. For more advanced Git development patterns, list multiple `branch_names` in the configuration, which will allow you to specify any of the configured branches when using the [commit files]({{navprefix}}/{{git-rest-api-guide}}#_commit_files) endpoint. ### Request parameters | Parameter | Description | | --- | --- | | `repository_url` | _String_. The HTTPS URL of the Git repository; for example, `https://github.com/user/repo.git`. | | `username` | _String_. Username to authenticate to the Git repository. | | `access_token` | _String_. Access token to authenticate to the Git repository. | | `org_identifier` | _String_. ID of the Org. Define this parameter only if the Orgs feature is enabled on your ThoughtSpot cluster and separate Orgs are configured for development and production environments. | | `branch_names` | _Array of strings_. List of Git branches to configure. | | `commit_branch_name` | _String_. Name of the remote branch where objects committed from this ThoughtSpot instance will be versioned. Replaces `default_branch_name`, which is deprecated in 9.10.5.cl. | | `default_branch_name` _Optional_ | _String_. Deprecated in 9.10.5.cl. In earlier versions, this parameter was used to configure the name of the default Git branch to use for all operations on the cluster. | | `enable_guid_mapping` | _Boolean_. Enables GUID mapping and generates a GUID mapping file. Starting from 9.7.0.cl, this attribute is set to `true` by default. To know more about GUID mapping, see [GUID mapping]({{navprefix}}/{{version_control}}#_guid_mapping_and_configuration_files). | | `configuration_branch_name` | _String_. Name of the branch where the configuration files related to operations between ThoughtSpot and the version control repository should be maintained. Replaces `guid_mapping_branch_name`, which is deprecated in 9.10.5.cl. > **NOTE:** If no branch name is specified, by default, the ts\_config\_files branch is considered. Ensure this branch exists before configuration. | | `guid_mapping_branch_name` _Optional_ | _String_. Deprecated in 9.10.5.cl. In earlier versions, this parameter was used to configure the name of the branch for the GUID mapping file. | | | | ### Request example The following example shows the API request format for connecting ThoughtSpot to a GitHub repository. ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host-Dev}/api/rest/2.0/vcs/git/config/create' \ -H 'Authorization: Bearer {Bearer_token}' \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ "repository_url": "https://github.com/user/repo.git", "username": "ts-git-user", "access_token": "{ACCESS_TOKEN}", "org_identifier": "dev", "branch_names": [ "dev", "main" ], "commit_branch_name": "dev", "configuration_branch_name": "_ts_config" }' ``` If the API request is successful, the ThoughtSpot instance will be connected to the Git repository. Go into each Org and issue the `config/create` call to link the appropriate branch to establish all environments. The following example shows the API request parameters to connect a ThoughtSpot `Prod` Org to the Git repo. Note that GUID mapping is enabled in the API request. The `Bearer_token` value must be requested for the desired Org, specified through the `org_id` value of the [full access token]({{navprefix}}/{{authentication}}#_generating_a_full_access_token) REST API request. ```cURL curl -X POST \ --url 'https://{ThoughtSpot-Host-Prod}/api/rest/2.0/vcs/git/config/create' \ -H 'Authorization: Bearer {Bearer_token}' \ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ "repository_url": "https://github.com/user/repo.git", "username": "ts-git-user", "access_token": "{ACCESS_TOKEN}", "enable_guid_mapping": true, "org_identifier": "prod", "branch_names": [ "prod" ], "enable_guid_mapping": true, "commit_branch_name": "prod", "configuration_branch_name": "_ts_config" }' ``` ### Initialize .mapping and .config files Version control and [GUID mapping]({{navprefix}}/{{guid-mapping}}) utilize files stored in the `configuration_branch`. You can initialize these files by immediately using the [deploy commits REST API]({{navprefix}}/{{git-rest-api-guide}}#_deploy_commits) after configuring the Org for Git. See the [create\_orgs\_with\_linked\_git\_branch.py script](https://github.com/thoughtspot/thoughtspot_rest_api_v1_python/blob/main/examples_v2/create_orgs_with_linked_git_branch.py) for an example of deploying a full Orgs or branches setup for structured development and deployment. After the Orgs are set up, you can [create connections across Orgs](https://github.com/thoughtspot/thoughtspot_rest_api_v1_python/blob/main/examples_v2/create_connection_on_orgs.py) and [add any necessary entries to the GUID mapping files]({{navprefix}}/{{guid-mapping}}#using-mapping-for-table-tml-properties). ## Update Git configuration To update the repository details or access token, send a `POST` request with Git configuration parameters to the `/api/rest/2.0/vcs/git/config/update` API endpoint. ## Search Git configuration To get repository configuration information, send a `POST` request to `/api/rest/2.0/vcs/git/config/search` API endpoint. ## Delete Git configuration To delete the repository configuration, send a `POST` request to the `/api/rest/2.0/vcs/git/config/delete` endpoint.