Available in beta, we have introduced new version control REST APIs for Git integration in the 9.3.0.cl release of ThoughtSpot Analytics Cloud.
ThoughtSpot administrators can now link their instances to a GitHub repository and utilize continuous integration and deployment (CI/CD) best practices to effectively manage their organization's analytic content throughout its lifecycle.
In this walkthrough, Nicolas Rentz, Senior Director of Product Management, demonstrates a typical process of committing objects from ThoughtSpot into GitHub, performing merges, and executing pull requests across multiple environments:
Managing analytic content with TML files
To give some background, ThoughtSpot business analytics content such as Liveboards, Answers, Worksheets, Data Connections, and more are all defined in a JSON-based metadata definition called ThoughtSpot Modeling Language, or TML for short.
Many ThoughtSpot customers use TML to support several scenarios:
Migrating from a development environment to a production environment by downloading files from the development cluster and uploading the same files into the production cluster
Implementing metadata changes outside the ThoughtSpot UI such as replacing the underlying tables for an object, or replacing a single column from one table with a column from another table
Making bulk changes such as the mass renaming of objects defined by Worksheets, and managing duplicates
Reusing existing objects to build new objects such as building two very similar objects based on a similar, pre-existing object.
Applying analytics-as-code principles, we initially developed a scriptable approach with TML to automate the lifecycle management of analytic content across environments.
TML and GitHub: like peanut butter and jelly
With Git integration, developers can now leverage GitHub repositories as a version control system and push TML files from development to production instances via CI/CD pipelines:
The new version control APIs for Git support the following scenarios:
Connect your ThoughtSpot instance to a Git repository
Perform commits for ThoughtSpot analytic content and even list the commit history for each item
Revert commits to a specific commit version in a Git branch
Perform validate merges to ensure that changes implemented in the source branch (i.e. dev) would function in the destination ThoughtSpot instance prior to merging a source branch into a target branch (i.e. master)
Deploy commits from the latest version of a Git branch to a destination ThoughtSpot instance.
Getting started with version control APIs
To begin, ensure that the following prerequisites are met:
You have admin access (can administer Thoughtspot privilege) to connect ThoughtSpot to a Git repository and deploy commits.
You have a Git repository and a branch that can be used as a default branch in ThoughtSpot.
You have a valid Git account with one of the following types of access tokens:
Personal access token (Classic) that 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 that allows Read access to metadata and Read and Write access to code and commit statuses.
With the access token, you can connect your ThoughtSpot instance to a Git repository using the Create Config API call (under “Version Control” in the ThoughtSpot developer portal) which sends a POST request to the /api/rest/2.0/vcs/git/config/create REST API v2.0 endpoint. Here’s an example of the request format:
curl -X POST \
--url 'https://{ThoughtSpot-Host}/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/ts-git-user/gitdemo",
"username": "ts-git-user",
"access_token": "{ACCESS_TOKEN}",
"branch_names": [
"dev",
"main"
],
"default_branch_name": "dev"
}'If the API request is successful, the ThoughtSpot instance will be connected to your Git repository. Make sure you connect all your environments (Dev, Prod, etc) to specific branches in your GitHub repository.
Committing TML files to Git
To commit updates and TML files to a specific branch in Git, use the Commit Branch API call which sends a POST request to the /api/rest/2.0/vcs/git/branches/commit API endpoint. Here’s an example of a request committing a Liveboard to Git:
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": "e9d54c69-d2c1-446d-9529-544759427075",
"type": "LIVEBOARD"
},
],
"comment": "New version of Sales Liveboard",
"branch_name": "dev"
}'On the roadmap
We’re continuously working to improve Git integration and aim to provide enhancements around GUID mapping and make it easier to manage diverging GUIs across different ThoughtSpot instances. Another focus area is providing support for ThoughtSpot Orgs. For example, if you have a single instance of ThoughtSpot and want to have separate tenants/Orgs behave as Development, Production, etc., you can link them to different Git branches in your Git repository.
Try it out
With Git integration now available, we aim to make the lifecycle management of analytic content easier and more seamless for you. Additionally, we hope this feature helps you implement best practices for CI/CD within your organization through ThoughtSpot.
Want to give it a try and share your thoughts with us? Reach out to our Support team and get the feature enabled on your ThoughtSpot cluster. We'd love to hear your feedback.
For more information, explore our open source Embed SDK and developer documentation on the new version control REST APIs for Git.
If you are new to ThoughtSpot Everywhere, ThoughtSpot Everywhere empowers product builders to create engaging, interactive experiences that get to market much faster than a home-grown feature set. You can use our embedded analytics toolkit to embed AI-Powered Analytics in your data products to give your users a live, intuitive natural language search experience combined with AI and free-form data exploration. Plus, you get done-for-you analytics services, robust APIs, and interactive developer resources your team will love.
See for yourself—go ahead and explore ThoughtSpot Everywhere right now. Or, if you’re curious about implementing ThoughtSpot Everywhere in your data products, you can start a free trial today.
