worked on documentation

.github/workflows/commit.yml

@@ -10,13 +10,16 @@ on:
   #   - cron: "20 5 * * *"
 
 
+
 env:
     # CS TOOLS IS COMMAND LINE LIBRARY WRAPPING TS APIS
     # https://thoughtspot.github.io/cs_tools/tools/git/
+    # Either use Secret key or Password
     CS_TOOLS_VERSION: v1.5.13b1
     CS_TOOLS_THOUGHTSPOT__URL: ${{ secrets.DEV_THOUGHTSPOT_URL }}
     CS_TOOLS_THOUGHTSPOT__USERNAME: ${{ secrets.DEV_THOUGHTSPOT_USERNAME }}
     CS_TOOLS_THOUGHTSPOT__SECRET_KEY: ${{ secrets.DEV_THOUGHTSPOT_SECRET_KEY }}
+    CS_TOOLS_THOUGHTSPOT__PASSWORD: ${{ secrets.THOUGHTSPOT_PASSWORD }}
 
     # THE NAME OF YOUR BRANCH / THOUGHTSPOT ENVIRONMENT.
     TS_ENV_NAME: ts-dev

.github/workflows/deploy.yml

@@ -12,10 +12,12 @@ on:
 env:
     # CS TOOLS IS COMMAND LINE LIBRARY WRAPPING TS APIS
     # https://thoughtspot.github.io/cs_tools/tools/git/
+    # Either use Secret Key or password
     CS_TOOLS_VERSION: v1.5.13b1
     CS_TOOLS_THOUGHTSPOT__URL: ${{ secrets.PRD_THOUGHTSPOT_URL }}
     CS_TOOLS_THOUGHTSPOT__USERNAME: ${{ secrets.PRD_THOUGHTSPOT_USERNAME }}
     CS_TOOLS_THOUGHTSPOT__SECRET_KEY: ${{ secrets.PRD_THOUGHTSPOT_SECRET_KEY }}
+    CS_TOOLS_THOUGHTSPOT__PASSWORD: ${{ secrets.PRD_THOUGHTSPOT_PASSWORD }}
 
     # THE NAME OF YOUR BRANCH / THOUGHTSPOT ENVIRONMENT.
     TS_ENV_NAME: ts-prod

.github/workflows/validate_ts_content.yml

@@ -0,0 +1,51 @@
+name: Validate Org Content
+
+on:
+  # ALLOW TRIGGERING ACTION MANUALLY
+  workflow_dispatch:
+    inputs:
+      target_org_id:
+        required: true
+        type: int
+      target_branch:
+        required: true
+        type: string
+
+  # AFTER A PULL REQUEST IS OPENED / COMMITTED TO
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      # ALLOW TRIGGERING ACTION ONLY SPECIFIC PRs
+      - '.github/PULL_REQUEST_TEMPLATE.md'
+
+
+env:
+    # CS TOOLS IS COMMAND LINE LIBRARY WRAPPING TS APIS
+    # https://thoughtspot.github.io/cs_tools/tools/git/
+    CS_TOOLS_VERSION: v1.5.13b1
+    CS_TOOLS_THOUGHTSPOT__URL: ${{ secrets.DEV_THOUGHTSPOT_URL }}
+    CS_TOOLS_THOUGHTSPOT__USERNAME: ${{ secrets.DEV_THOUGHTSPOT_USERNAME }}
+    CS_TOOLS_THOUGHTSPOT__SECRET_KEY: ${{ secrets.DEV_THOUGHTSPOT_SECRET_KEY }}
+
+    # THE NAMES OF YOUR BRANCH / THOUGHTSPOT ENVIRONMENTS TO VALIDATE CHANGES BETWEEN.
+    #TS_DESTINATION_ORG_ID: ${{ github.event_name == 'workflow_dispatch' && inputs.target_org_id || github.head_ref }}
+    #TS_TARGET_ENV_NAME: ${{ github.event_name == 'workflow_dispatch' && inputs.target_branch || github.base_ref }}
+
+
+jobs:
+  run_validate_api:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checking out the repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Install CS Tools
+        run: pip install "cs_tools[cli] @ https://github.com/thoughtspot/cs_tools/archive/${{ env.CS_TOOLS_VERSION }}.zip"
+
+      - name: Run the GIT VALIDATE command
+        run: "cs_tools tools git branches deploy --deploy_policy VALIDATE_ONLY --branch-name ${{ env.TS_TARGET_ENV_NAME }} --org ${{ env.TS_DESTINATION_ORG_ID }} --config ENV:"

info/config.md

@@ -87,8 +87,11 @@ On acceptance and merge of the PR, changes are deployed to the __ThoughtSpot__ O
 ## How should I set up my ThoughtSpot?
 
 - Go to Develop tab of Org for which you want to create __Config__
-- In __Rest API__ Section, select [ __REST Playground v1__ ](https://try-everywhere.thoughtspot.cloud/v2/#/everywhere/api/rest/playgroundV2_0)
+- In __Rest API__ Section, select [ __REST Playground v2__ ](https://developers.thoughtspot.com/docs/rest-apiv2-reference#_version_control)
 - In __API ENDPOINT__ section, select version control where we need to create a config file.
-- Create a config for __Thoughtspot__ to login to __Github REPO__ where you want to do version control of __TS__ Objects.
+- Create a config Option for __Thoughtspot__ to login to __Github REPO__ where you want to do version control of __TS__ Objects.
 - Provide the [__Parameters__](https://developers.thoughtspot.com/docs/git-configuration#_request_parameters)
-- To get repository configuration information, select [__Search__ ](https://developers.thoughtspot.com/docs/git-configuration#_search_git_configuration)API 
+- To get repository configuration information, select [__Search__ ] Endpoint API
+
+> [!NOTE]
+> To Setup Github Secret, follow offical Github Documentation and these [__steps__](info/github_secrets.md)

info/deploy.md

@@ -1,6 +1,18 @@
-# How Deploy Object From Dev To Prod
-- After Object moves to ts-dev Branch in Github, we can raise [__Pull_Request__](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#about-pull-requests) to move object to ts-prod Branch.
-- Fill the PR Template (.github/pull_request_template.md) with necassary information to get it review by admin.
-- During the Review a [__Validate__](.github/workflows/validate.yml) Test will run to check if we can to ensure the TML content in target environments can import changes without conflicts.
-- After Successfull Test, we will merge oue changes to ts-prod branch, it will run [__Deploy_Workflow__](.github/workflows/deploy.yml) which will pick the recent object from PR, import these object production environment.
+### Deployment Process: Moving Objects from Dev to Prod
+
+## Once the object commited to ts-dev branch, then following steps ensure a smooth deployment:
+
+- After an object moves to the ts-dev branch in GitHub, create a [__Pull Request__](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to move it to the ts-prod branch.
+
+- Fill in the required details in the [__PR Template__](.github/pull_request_template.md) to get it reviewed by an admin.
+
+- During the review process, a [__Validate Test__](info/validate.md) will run to ensure the TML content in the target environment can be imported without conflicts.
+
+- If the validate test passes, merged the objects into ts-prod branch.
+
+- Merging triggers the [__Deploy Workflow__](.github/workflows/deploy.yml), which picks the latest commit object from the PR and imports it into the production environment.
+
+- The deploy API is triggered automatically, ensuring that the deployment process is carried out seamlessly.
+
+## This structured approach ensures a seamless and conflict-free deployment process.
 

info/github_secrets.md

@@ -0,0 +1,44 @@
+
+## How should I set up my Github Action?
+## To securely store credentials and configuration values required for GitHub Actions, follow these steps:
+
+> [!CAUTION]
+> Ensure the Workflow is in the Main Branch
+
+[__Step 1__]: 
+- Navigate to GitHub Secrets
+
+- Go to your repository on GitHub.
+
+- Click on Settings.
+
+- In the left sidebar, click Secrets and variables > Actions.
+
+- Click New repository secret.
+
+[__Step 2__]: 
+
+- Add Required Secrets
+
+- Create the following secrets one by one:
+
+- Secret Name: DEV_THOUGHTSPOT_URL , Value: Your Dev Org URL
+
+- Secret Name: DEV_THOUGHTSPOT_USERNAME , Value: Admin Username of the cluster
+
+> [!WARNING]
+> Either Use DEV_THOUGHTSPOT_SECRET_KEY or DEV_THOUGHTSPOT_PASSWORD
+
+- Secret Name: DEV_THOUGHTSPOT_SECRET_KEY , Value: Trusted Auth
+
+- Secret Name: DEV_THOUGHTSPOT_PASSWORD , Value: Admin Password
+
+> [!NOTE]
+> If you are using CI/CD for same cluster, you only need these 3 secrets but if there is another cluster please configure the secret for Prod also with PROD_ Suffix
+
+[__Step 3__]: 
+- Verify and Use Secrets in Workflows
+
+- After adding secrets, they can be accessed within GitHub Actions using ${{ secrets.SECRET_NAME }}.
+
+- Ensure your workflows correctly reference these secrets for authentication and deployment.

info/org_config.md

@@ -0,0 +1,20 @@
+### Creating a Configuration in ThoughtSpot
+## To ensure best practices in version control, it is recommended to create the configuration using the V2 API.
+
+- Configuration Parameters
+- When setting up the configuration, the following parameters must be defined:
+
+  - repository_url → The URL of the GitHub repository (e.g., https://github.com/thoughtspot/ts-ci-github).
+  - username → The username of an account with admin privileges.
+  - access_token → A GitHub-provided token that allows ThoughtSpot to access the repository.
+  - branch_names → The branch for which the configuration is being created.
+  - enable_guid_mapping → Set to true by default.
+  - configuration_branch_name → A separate configuration branch (recommended name: ts-config).
+
+## Steps to Create the Configuration
+- Use the V2 API to send a request with the above parameters.
+- Upon successful execution, a success message will be displayed.
+- Verify the newly created configuration using the [Search Config API].
+- Repeat the process for any additional organizations that require configuration.
+
+## By following these steps, you ensure a standardized and structured approach to version control configuration in ThoughtSpot.

info/validate.md

@@ -1,5 +1,40 @@
-## Validating the objects between two environment
-- Before moving the objects between two environment we should test the compability between these two environment
-- for that we will use (__validate_API__)[https://developers.thoughtspot.com/docs/git-api#_validate_merge]
-- After validating the merge, check for conflicts. Resolve issues if any with a new commit and merge your changes to the ts-prod branch.
-- ......
+### Pull Request Validation: Ensuring Compatibility Before Merging
+
+To maintain consistency and avoid conflicts when merging changes, we enforce validation tests between environments. If these tests fail, **the pull request should not be merged**.
+
+## Validation Types
+
+### 1. **Validation Between GitHub Branches**
+
+Before merging changes between branches, we must ensure compatibility between the environments. This prevents potential failures in downstream deployments.
+
+- We achieve this using the [__validate_API__](https://developers.thoughtspot.com/docs/git-api#_validate_merge).
+- Our workflow automates this validation through [__validate_git_merge__](.github/workflows/validate_git_merge.yml).
+- If the validation fails, **the pull request should be blocked**.
+- If conflicts are detected, resolve them with a new commit before attempting the merge again.
+
+### 2. **Validation Between Organizations (Orgs)**
+
+When modifying TML content, we must ensure that the destination environment can import the changes without issues.
+
+- This prevents unintended modifications in the target environment after merging changes from the development branch.
+- Our workflow runs validation using [__validate_ts_content__](.github/workflows/validate_ts_content.yml).
+- If the validation fails, the pull request **must not be merged** until the conflicts are resolved.
+
+### Enforcement
+
+- **All PRs must pass these validation tests before merging.**
+- If any test fails, the PR should remain open until the issues are fixed.
+- This ensures smooth deployments and consistency across environments.
+
+## Validate Manually
+
+1. Ensure your [__Validate Workflow Files__] has been configured with the correct environment variables.
+2. Then, [__visit the workflow__] and click the `Run Workflow` button.
+
+<center>
+      <figure>
+          <img src="workflow_validate.png" alt="run-validate" width="500" />
+          <figcaption><i>Manually trigger the Validate between Orgs</i></figcaption>
+      </figure>
+</center>

info/workflow_validate.md

@@ -0,0 +1 @@
+<img width="557" alt="Screenshot 2025-02-12 at 5 31 10 PM" src="https://github.com/user-attachments/assets/2cefebae-2078-463f-971e-0cd2ee524349" />