The /vcs/git/ endpoints of the v2.0 REST API provide all the functionality necessary to configure, perform version control, and deploy changes to different ThoughtSpot environments, other than configuring connections.
The basic process involves the following steps:
Commit changes into a "dev" branch from the "dev" Org
Move those changes to other branches via Git
Deploy commits into the destination Org (eventually "main" or "prod")
The following sections describe how to use the version control REST APIs after completing Git configuration for a ThoughtSpot instance.
There is a complete implementation of all Git REST APIs available in the CS Tools package as well as example workflow scripts available in Python.
The /api/rest/2.0/vcs/git/branches/commit API call exports the TML files for the requested ThoughtSpot objects directly to a Git branch and commits the changes.
You must specify each object to commit within the metadata parameter, with either the object’s guid or a combination of the name and the type.
To get the list of objects to commit, either use the GUID visible in the ThoughtSpot UI URL or use the /metadata/search endpoint to retrieve a filtered list of objects within ThoughtSpot.
If you do not specify the branch_name argument, the commit will be pushed to the commit_branch_name defined for the Git connection configuration.
Note that you can only specify a branch_name that has been configured for the Org.
| Parameter | Description | ||
|---|---|---|---|
| Array of Strings. Specify the | ||
| Boolean. When
| ||
| String. Name of the branch in the Git repository to which you want to push the commit. If you do not specify the branch name, the commit will be pushed to the | ||
| String. Add a comment to the commit. | ||
The following example shows the API request with Liveboard and Worksheet objects to commit to the default commit_branch_name for the Org the request is issued on (controlled by the bearer token):
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/vcs/git/branches/commit' \
-H 'Authorization: Bearer {Bearer_token}\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"metadata": [
{
"identifier": "Liveboard with Unique Name",
"type": "LIVEBOARD"
},
{
"identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca"
}
],
"delete_aware": true,
"comment": "Add objects"
}'During this operation, a check is performed to compare the objects in the Git branch with the objects in the ThoughtSpot environment.
If an object exists in the Git branch, but not in the ThoughtSpot instance or Org, the object will be deleted from the Git branch.
If the object does not exist in the Git branch, it will be added to the Git branch specified in the API request or commit_branch_name configured for the Git connection.
If the object exists on both the Git branch and ThoughtSpot cluster or Org and there are no changes detected in the commit, the API returns a warning message with a list of objects that were not updated as part of the commit.
The following figure illustrates the commit operation with the delete_aware property enabled:
The /api/rest/2.0/vcs/git/commits/deploy endpoint imports the TML files from the last commit in a Git branch back into the ThoughtSpot Org the REST API command is used to, controlled by the bearer token of the REST API request.
You must specify the branch_name of the commits to deploy from. In the standard deployment patterns, the branch name should be the commit_branch_name defined for the Org in the Git configuration, also called the environment branch.
In a single-tenanted deployment pattern, you might instead deploy to each end-customer Org from the "release" / "pre-prod" branch rather than deploy from the branch of the Org’s environment. If you have any additional processes to run on the TML files prior to final deployment, it is preferable to merge changes to the environment branch and then deploy commits from the environment branch.
The API will deploy the head of the specified Git branch unless a commit_id is specified in the API request. If your team uses tags or releases, supply the commit_id from Git associated with the release or tag.
Because each Org in ThoughtSpot has distinct objects with their own GUIDs, the import process for objects originating from a different environment requires swapping in the correct GUIDs.
If you have enabled GUID mapping in the Git configuration on your deployment instance, the version control APIs automatically generate a GUID mapping file and update object references when deploying your commits to the destination environment.
See the GUID mapping documentation to understand how it works and the additional capabilities for handling other substitutions that may be necessary during deploying commits to the destination environment.
The example script in Python shows the pattern of deploying to "prod org per customer" from a single pre_prod/release branch, to avoid the need for pull requests into each branch linked to an end customer Org.
|
Note
|
Parallel deployment to multiple organizations within a single cluster is not supported. Developers must run deployments to each organization sequentially. |
| Parameter | Description |
|---|---|
| String. ID of the commit to deploy on the cluster. By default, the command will deploy the head of the branch. To deploy a specific version, specify the |
| String. Name of the branch from which the commit must be picked for deployment. |
| String. Specify one of the following options:
|
| String. Action to apply when deploying a commit. The allowed values are:
|
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/vcs/git/commits/deploy' \
-H 'Authorization: Bearer {Bearer_token}'\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"deploy_type": "DELTA",
"deploy_policy": "ALL_OR_NONE",
"commit_id": "afc0fea831558e30d7064ab019f49243b1f09552",
"branch_name": "main"
}'If the API request is successful, the changes are applied to the objects in the prod environment. A tracking file is generated in the Git branch used for storing configuration files. This file includes the commit_id specified in the API request.
The subsequent API calls to deploy commits will consider the saved commit_id and deploy_type specified in the API request:
If deploy_type is set as DELTA, all the changes between the last tracked commit id and the new commit_id specified in the API request will be deployed to the destination environment or Org.
If the deploy_type is FULL, all the files from the commit_id specified in the API request will be deployed. If any object or file is deleted in the commit specified in the API request, it will be deleted from the destination environment during deployment.
To merge updates, create a pull request to push changes from your dev branch to main. ThoughtSpot doesn’t provide REST APIs to merge content from one branch to another. Before accepting the merge request in the Git repository, you can validate the merge on your ThoughtSpot instance using REST API.
To validate the content of your dev branch against your prod environment, send a POST request from your prod instance to the /api/rest/2.0/vcs/git/branches/validate API endpoint.
|
Note
|
Due to GUID mapping requirements in most destination environments, it is currently preferable to use the Deploy Commits endpoint with the |
| Parameter | Description |
|---|---|
| String. Name of the source branch from which changes need to be picked for validation. |
| String. Name of the target branch into which the TML changes will be merged. |
The following example shows the API request with Liveboard and Worksheet objects to commit to Git.
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/vcs/git/branches/validate' \
-H 'Authorization: Bearer {Bearer_token}\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"source_branch_name": "dev",
"target_branch_name": "main"
}'After validating the merge, check for conflicts. Resolve issues if any with a new commit and merge your changes to the main branch.
ThoughtSpot provides a REST API endpoint to search commits for a given TML object. A POST call to the /api/rest/2.0/vcs/git/commits/search endpoint with metadata identifier and type in the request body fetches a list of commits.
To undo the changes committed to a repository, revert to a previous commit and restore an earlier version of an object using the /v2/vcs/commits/{commit_id}/revert API endpoint.
| Parameter | Description |
|---|---|
| String. ID of the commit to which you want to revert. |
| Array of Strings. Specify the |
| String. Name of the branch to which the revert operation must be applied. If you do not specify the branch name, the API will revert the commit to the default branch configured on that ThoughtSpot instance. |
| String. Action to apply when reverting a commit. The allowed values are:
|
The following example shows the API request for reverting a commit.
curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/vcs/git/commits/afc0fea831558e30d7064ab019f49243b1f09552/revert' \
-H 'Authorization: Bearer {Bearer_token}\\
-H 'Accept: application/json'\
-H 'Content-Type: application/json' \
--data-raw '{
"metadata": [
{
"identifier": "e9d54c69-d2c1-446d-9529-544759427075",
"type": "LIVEBOARD"
}
],
"commit_id": "afc0fea831558e30d7064ab019f49243b1f09552",
"branch_name": "dev"
}'If the API request is successful, the Git branch is reverted to the specified commit ID.