diff --git a/docs/user-guide/creating-application/fluxcd.md b/docs/user-guide/creating-application/fluxcd.md
index f7bb5ea805..23555f5688 100755
--- a/docs/user-guide/creating-application/fluxcd.md
+++ b/docs/user-guide/creating-application/fluxcd.md
@@ -34,10 +34,6 @@ To enable deployments through GitOps via FluxCD, you need to enable a specific f
|**Deployments via FluxCD**|`FEATURE_FLUX_DEPLOYMENTS_ENABLE: "true"`|This flag will enable deployments through GitOps via FluxCD.
After enabling this flag, you also need to install FluxCD controller in order to deploy applications successfully. Refer [Installing FluxCD Controller](#installing-fluxcd-controller-only-for-deployments) to know more.
|
|**Migrating existing FluxCD applications**|`FEATURE_LINK_EXTERNAL_FLUX_ENABLE: "true"`|This flag will enable migrations for external FluxCD apps into Devtron.|
- :::caution Deployment Strategies for FluxCD Deployments
- Application deployments through GitOps (via FluxCD) are supported only when using the `Deployment` or `Rollout` deployment strategies with the latest chart versions. Other deployment strategies are currently not supported.
-:::
-
### Enabling Feature Flags
1. Navigate to Devtron's **Resource Browser**.
@@ -128,7 +124,7 @@ You can install FluxCD Controller by any of the following ways:
4. Run the following command to install the FluxCD Controller:
```yaml
- kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v0.35.0/install.yaml
+ kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.7.5/install.yaml
```
@@ -173,4 +169,32 @@ To install FluxCD controller via Chart Store, follow the below steps.
6. Click **Deploy** and the chart will be deployed.
-After the chart is successfully deployed, you can deploy applications though GitOps (via FluxCD).
\ No newline at end of file
+After the chart is successfully deployed, you can deploy applications though GitOps (via FluxCD).
+
+## Advanced Configuration (Optional)
+
+The following **orchestrator** environment variables tune the status-polling and timeout cadence for FluxCD apps. They do **not** enable any feature — the defaults are sensible, so change them only if you have a specific need. Note these are set on the **orchestrator**, not in the `dashboard-cm` ConfigMap used for the feature flags above.
+
+| Env variable | Default | Purpose |
+|---|---|---|
+| `CD_FLUX_PIPELINE_STATUS_CRON_TIME` | `*/2 * * * *` | Cron frequency for checking FluxCD CD-pipeline deployment status |
+| `FLUX_CD_PIPELINE_STATUS_CHECK_ELIGIBLE_TIME` | `120` (sec) | Re-check a pipeline's status only if it was not updated within this window |
+| `FLUX_INSTALLATION_STATUS_CRON_TIME` | `1` (min) | Polling interval for tracking FluxCD installation status |
+| `FLUX_INSTALLATION_DELETE_CRON_TIME` | `1` (min) | Polling interval for tracking FluxCD installation delete status |
+| `FLUX_INSTALLATION_HELM_RELEASE_CRON_TIME` | `30` (sec) | Scan interval for HelmReleases stuck in *Applying* (timeout) or *Pending* (missed event) |
+| `FLUX_APPLY_STATUS_TIMEOUT` | `2` (min) | Duration after which a HelmRelease moves from *Applying* to *TimedOut* |
+| `FLUX_PENDING_STATUS_TIME` | `3` (min) | Duration after which an event is emitted for an install stuck in *Pending* |
+
+## Limitations
+
+Keep the following limitations in mind when using GitOps deployments via FluxCD:
+
+* **No manual sync from Devtron**: There is no manual *sync* or *refresh* action for FluxCD applications in Devtron. Deployments reconcile automatically on FluxCD's reconciliation interval. To force an immediate reconcile, use the FluxCD CLI, for example:
+
+ ```bash
+ flux reconcile helmrelease -n
+ ```
+
+* **Manual controller setup required**: Devtron does not install the FluxCD controller automatically. You must install it in every target cluster (see [Installing FluxCD Controller](#installing-fluxcd-controller-only-for-deployments)) and enable the required feature flags before you can deploy.
+
+* **Prerequisites**: FluxCD deployments require the [Build and Deploy (CI/CD)](../integrations/build-and-deploy-ci-cd.md) and [GitOps (ArgoCD)](../integrations/argocd.md) integrations to be installed.
\ No newline at end of file
diff --git a/docs/user-guide/creating-application/workflow/ci-pipeline.md b/docs/user-guide/creating-application/workflow/ci-pipeline.md
index a10e00f863..a53cb26df1 100755
--- a/docs/user-guide/creating-application/workflow/ci-pipeline.md
+++ b/docs/user-guide/creating-application/workflow/ci-pipeline.md
@@ -817,6 +817,19 @@ You have the option to ignore cache while triggering a build (regardless of the
If the caching flags in **Global Settings** are set to false, ignoring cache becomes the default behavior even if you don't select the 'Ignore Cache' checkbox during trigger.
:::
+#### Caching for Multi-Architecture Builds
+
+When you build for multiple [target platforms](../../creating-application/docker-build-configuration.md#set-target-platform-for-the-build) (multi-architecture builds), Devtron uses BuildX and, when caching is enabled, maintains a **separate build cache per target architecture** so that each platform's layers are reused across builds.
+
+Super-admins can tune multi-architecture build caching using the following additional flags in the `orchestrator-cm` ConfigMap:
+
+| Flag | Default | Description |
+|:---|:---|:---|
+| `BUILDX_CACHE_MODE_MIN` | `false` | Controls the BuildX cache mode. When `false`, mode `max` is used — all intermediate layers are cached for maximum reuse, at the cost of a larger cache. When `true`, mode `min` is used — only the final exported layers are cached, resulting in a smaller cache. |
+| `ASYNC_BUILDX_CACHE_EXPORT` | `false` | When `true`, the BuildX cache is exported **asynchronously after** the build completes, which can reduce build time. This applies only when using a multi-node BuildX Kubernetes driver. |
+
+After updating these flags, restart the orchestrator deployment for the changes to take effect.
+
### Override Build Configuration
**Override Options** in **Build Stage** lets you override **Build Configurations** for each workflow of the same application. You can configure overrides in the build stage of each workflow.
diff --git a/docs/user-guide/devtron-intelligence.md b/docs/user-guide/devtron-intelligence.md
index 434c6d5181..f694a602b8 100755
--- a/docs/user-guide/devtron-intelligence.md
+++ b/docs/user-guide/devtron-intelligence.md
@@ -1,6 +1,3 @@
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
# Using Devtron Intelligence
## What is Devtron Intelligence (AI Agent)
@@ -12,306 +9,180 @@ Check out the [Results](#results) section to see where Devtron gives you AI-powe
Figure 1: Devtron Intelligence for AI-assisted Debugging
-### Tutorial
-
-
-
----
+## Capabilities
-## Steps to Configure Devtron Intelligence
-
-:::caution Who Can Perform This Action?
-User must have permissions to:
- * Deploy Helm Apps (with environment access)
- * Edit the ConfigMaps of 'default-cluster'
- * Restart the pods
-:::
+Devtron Intelligence is an AI agent that can reason over your Devtron-managed Kubernetes estate and assist you across several areas:
-### 1. Get API Key from LLM
+* **Explain with AI** — Analyze pod errors, restart snapshots, events, and application status, and get easy-to-understand explanations and remediation steps.
-Devtron Intelligence supports all major large language models (LLM) e.g., OpenAI, Gemini, AWS Bedrock, Anthropic and many more.
+* **AI Debug (autonomous root-cause)** — Investigate Kubernetes issues autonomously (powered by Holmes) and return a detailed root-cause analysis.
-You can generate an API key for an LLM of your choice. Here, we will generate an API key from [OpenAI](https://platform.openai.com/account/api-keys).
+* **Ask Devtron Expert (chatbot)** — Ask free-form questions about your applications and Kubernetes issues in a chat side panel.
+* **Cost insights** — Answer questions about cost breakdown and cost summary for your applications and clusters.
-### 2. Create Secret in Devtron
+* **Application and resource Q&A** — Query applications, environments, projects, jobs, Helm apps, manifests, and resource utilization in natural language.
-There are 2 methods to create a secret in Devtron, follow the one you prefer:
-* [Method A: Using 'Create Resource'](#method-a-using-create-resource)
-* [Method B: Using kubectl command](#method-b-using-kubectl-command)
+* **Documentation search** — Answer product questions grounded in Devtron's documentation.
-#### Method A: Using 'Create Resource'
-
-1. Go to [strings.devtron.ai](https://strings.devtron.ai/base64-encoder) and encode your API key in base64. This base64 encoded key will be used while creating a secret in the next step.
-
-2. Go to **Infrastructure Management** → **Resource Browser** → (Select Cluster) → **Create Resource**
-
-3. Paste the following YAML and replace the key with your base64-encoded OpenAI key. Also, enter the namespace where the [AI Agent chart](#3-deploy-ai-agent-chart) will be installed:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
- name: ai-secret
- namespace: # Namespace where the AI Agent chart will be installed
-type: Opaque
-data:
- ## OpenAiKey: # For OpenAI
- ## GoogleKey: # For Gemini
- ## azureOpenAiKey: # For Azure OpenAI
- ## awsAccessKeyId: # For AWS Bedrock
- ## awsSecretAccessKey: # For AWS Bedrock
- ## AnthropicKey: # For Anthropic
-```
-
-#### Method B: Using kubectl command
-
-:::tip
-Unlike [Method A](#method-a-using-create-resource), this method doesn't require you to encode your LLM Key to Base64 format.
-:::
-
-1. Go to Devtron's [Resource Browser](./resource-browser/README.md) and click the [terminal icon](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/cluster-terminal.gif) next to the cluster where you wish to create the secret.
-
-2. Use the following kubectl command to create a secret.
- * Replace `my-namespace` with the namespace where the AI Agent chart will be installed.
- * Use the correct LLM key-name and your key-value after `--from-literal`
-
-```bash
-kubectl create secret generic ai-secret \
- --namespace=my-namespace \
- --from-literal=OpenAiKey='openai-key-here' \
-# --from-literal=GoogleKey='google-key-here' \
-# --from-literal=azureOpenAiKey='azure-key-here' \
-# --from-literal=AnthropicKey='anthropic-key-here'
-```
-
- 
-
Figure 2: Creating Secret using Cluster Terminal
-
-
-### 3. Deploy AI Agent Chart
-
-:::caution Where should I install the Chart?
-Deploy the chart in the cluster whose workloads you wish to troubleshoot. You may install the chart in multiple clusters (1 agent for 1 cluster).
-:::
-
-1. Go to Devtron's Chart Store.
+---
-2. Search the `ai-agent` chart and click on it.
+## How It Works
-3. Click the **Configure & Deploy** button.
+Devtron Intelligence is powered by the **Athena** backend, which is deployed by the **Devtron enterprise Helm chart** on the cluster where the orchestrator runs. When enabled, it brings up three services:
-4. In the left-hand pane:
+* **`athena-api`** — the agent/chat service; it also runs the AI Debug capability via Holmes.
+* **`athena-mcp`** — the MCP engine that exposes Devtron operations to the agent.
+* **worker engine** — a background worker for recommendations and remediation.
- * **App Name**: Give your app a name, e.g. `ai-agent-app`
+These are backed by a bundled **Redis** cache and a dedicated **`athena`** database in Devtron's PostgreSQL. You enable and configure the whole backend through the chart's `devtronEnterprise.athenaApi` values, then turn the feature on in Devtron.
- * **Project**: Select your project
+## Prerequisites
- * **Deploy to environment**: Choose the target environment (should be associated with the same namespace used while creating secret key in [Step 2](#2-create-secret-in-devtron))
+Before you begin, make sure you have:
- * **Chart Version**: Select the latest chart version.
+* **Devtron Enterprise** — Devtron Intelligence (the Athena backend) is an enterprise-only capability. If you don't have it yet, [install Devtron](../setup/install/README.md) and [activate an Enterprise license](../setup/install/devtron-freemium.md#update-license) first.
+* **An LLM provider API key** — a credential for the model provider you want to use (OpenAI, Anthropic, Gemini, AWS Bedrock, or any other [LiteLLM](https://docs.litellm.ai/)-supported provider).
+* **Access** — the ability to set values on the Devtron enterprise Helm chart (or a DevOps contact who can), plus permission to edit **ConfigMaps** and restart **workloads** on the cluster where the Devtron orchestrator runs.
- * **Chart Values**: Choose the default one for the latest version.
+---
-5. In the `values.yaml` file editor, add the appropriate `additionalEnvVars` block based on your LLM provider. Use the tabs below to find the configuration snippet of some well-known LLM providers.
+## Steps to Configure Devtron Intelligence
-
+Setting up Devtron Intelligence takes four steps: get an LLM API key, enable Athena while installing/upgrading the enterprise chart, turn the feature on in Devtron, and restart the affected workloads.
-
-```yaml
-additionalEnvVars:
- - name: MODEL
- value: gpt-4o-mini ## Examples: gpt-4o, gpt-4, gpt-3.5-turbo
- - name: OPENAI_API_KEY
- valueFrom:
- secretKeyRef:
- key: OpenAiKey ## Key of the secret created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: CLUSTER_NAME
- value: document-nonprod ## Name of the target cluster (optional)
-```
-
+### 1. Get an LLM API Key
-
-```yaml
-additionalEnvVars:
- - name: MODEL
- value: gemini/ ## Examples: gemini/gemini-1.5-pro, gemini/gemini-2.0-flash
- - name: GOOGLE_API_KEY
- valueFrom:
- secretKeyRef:
- key: GoogleKey ## Key of the secret created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: CLUSTER_NAME
- value: document-nonprod ## Name of the target cluster (optional)
-```
-
+Devtron Intelligence supports all major LLM providers (OpenAI, Gemini, AWS Bedrock, Anthropic, and more, via LiteLLM). Generate an API key (or credential) for the provider you want to use — you will supply it to the chart in the next step.
-
-```yaml
-additionalEnvVars:
- - name: MODEL
- value: azure/ ## Replace with your Azure deployment name (keep "azure/" prefix)
- - name: MODEL_TYPE
- value: gpt-4o ## Supported: gpt-4o, gpt-35-turbo, etc.
- - name: AZURE_API_VERSION
- value: ## Replace with the version from Azure portal
- - name: AZURE_API_BASE
- value: ## Your Azure endpoint e.g. https://my-org.openai.azure.com/
- - name: AZURE_API_KEY
- valueFrom:
- secretKeyRef:
- key: azureOpenAiKey ## Key of the secret created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: CLUSTER_NAME
- value: document-nonprod ## Name of the target cluster (optional)
-```
-
+### 2. Enable and Configure Athena (Enterprise Chart)
-
-```yaml
-additionalEnvVars:
- - name: MODEL
- value: bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0 ## Replace with your actual Bedrock model name
- - name: AWS_REGION_NAME
- value: us-east-1
- - name: AWS_ACCESS_KEY_ID
- valueFrom:
- secretKeyRef:
- key: awsAccessKeyId ## Key of the Access Key ID created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: AWS_SECRET_ACCESS_KEY
- valueFrom:
- secretKeyRef:
- key: awsSecretAccessKey ## Key of the secret created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: CLUSTER_NAME
- value: document-nonprod ## Name of the target cluster (optional)
-```
-
+Athena is configured **while [installing or upgrading](../setup/install/README.md) the Devtron enterprise Helm chart** — there is no separate installer for it. Provide the following under the chart's `devtronEnterprise.athenaApi` values (`enabled: true`, your model, and your LLM credential):
-
```yaml
-additionalEnvVars:
- - name: MODEL
- value: claude-3-sonnet ## Examples: claude-3-sonnet, claude-3-haiku
- - name: ANTHROPIC_API_KEY
- valueFrom:
- secretKeyRef:
- key: AnthropicKey ## Key of the secret created in Step 2
- name: ai-secret ## Name of the secret created in Step 2
- - name: CLUSTER_NAME
- value: document-nonprod ## Name of the target cluster (optional)
+devtronEnterprise:
+ athenaApi:
+ enabled: true
+ configs:
+ LLM_MODEL_ID: "" # e.g. gpt-4o, claude-<...>, gemini/<...>, bedrock/<...>
+ LLM_TEMPERATURE: "0.01" # default
+ REDIS_URL: redis://redis.devtroncd # bundled Redis (default — leave as-is)
+ PG_DATABASE: athena # dedicated Athena database (default — leave as-is)
+ secrets:
+ # LLM credential — use the key name that matches your provider (one of):
+ OPENAI_API_KEY: "" # OpenAI
+ # AWS_BEARER_TOKEN_BEDROCK: "" # AWS Bedrock
+ # GEMINI_API_KEY: "" # Gemini
+ # ANTHROPIC_API_KEY: "" # Anthropic
```
-
-
-
-
-
-
Figure 3: Chart Configuration
-
-6. Click the **Deploy Chart** button.
-
-### 4. Check Service Endpoint
-
-1. In the **App Details** page of the deployed chart, expand **Networking** and click on **Service**.
-
-2. Locate the service entry with the URL in the format: `.:`. Note the values of `serviceName`, `namespace`, and `port` for the next step.
-
-
-
Figure 4: Service Endpoint of AI Agent Helm App
+| Key | Description |
+|:---|:---|
+| `athenaApi.enabled` | Set to `true` to deploy the Athena backend (`athena-api`, `athena-mcp`, and the worker engine). Default `false`. |
+| `athenaApi.configs.LLM_MODEL_ID` | The chat/agent model. The format depends on the provider — e.g. `gpt-4o`, `claude-<...>`, `gemini/<...>`, `bedrock/<...>`. |
+| `athenaApi.configs.LLM_TEMPERATURE` | LLM temperature. Default `0.01`. |
+| `athenaApi.configs.REDIS_URL` | Connection to the bundled Redis cache. Defaults to `redis://redis.devtroncd`; leave unchanged unless you point Athena at an external Redis. |
+| `athenaApi.configs.PG_DATABASE` | The database Athena uses within Devtron's PostgreSQL. Defaults to `athena` and is created automatically. |
+| `athenaApi.secrets` | Your LLM credential. The chart renders it into a Kubernetes Secret that Athena consumes. |
+
+:::note
+Athena uses **LiteLLM**, so the credential key name is LiteLLM's standard variable for your provider, selected by the `LLM_MODEL_ID` prefix — for example `OPENAI_API_KEY` (OpenAI), `ANTHROPIC_API_KEY` (Anthropic), `GEMINI_API_KEY` (Gemini), or AWS credentials for `bedrock/...` models (`AWS_BEARER_TOKEN_BEDROCK`, or `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION_NAME`).
+:::
-### 5. Update ConfigMaps
+:::caution
+Do not commit real credentials to a values file in Git. Supply them at install/upgrade time (for example, a separate secrets values file or your installer's secret store).
+:::
-1. In a new tab, go to **Infrastructure Management** → **Resource Browser** → (Select Cluster) → **Config & Storage** → **ConfigMap**
+**Install or upgrade the Devtron enterprise chart with these values applied** (via your Devtron installer or `helm upgrade`). This deploys the `athena-api`, `athena-mcp`, and worker services, the Redis cache, and provisions the `athena` database. Wait until the Athena pods are **Running** before continuing.
-2. Edit the ConfigMaps:
+:::note
+How you apply these values depends on how your Devtron is installed. If Devtron manages your cluster for you, ask your Devtron/DevOps contact to enable `athenaApi` with your model and credential.
+:::
- * **devtron-cm**
+### 3. Enable the Feature in Devtron
- Ensure the below entry is present in the ConfigMap (create one if it doesn't exist). Here you can define the target cluster and the endpoint where your Devtron AI service is deployed:
+Once the Athena pods are running, turn the feature on in Devtron. Go to **Infrastructure Management** → **Resource Browser** → (Select Cluster) → **Config & Storage** → **ConfigMap**, and edit:
- ```yaml
- CLUSTER_CHAT_CONFIG: '{"": {"serviceName": "", "namespace": "", "port": ""}}'
- ```
+* **orchestrator-cm** — enable the chatbot and register the Athena service proxy:
- 
-
Figure 5: Entry in 'orchestrator-cm' or 'devtron-cm' ConfigMap
+ ```yaml
+ FEATURE_ASK_DEVTRON_EXPERT: "true"
+ PROXY_SERVICE_CONFIG: '{"athena":{"host":"","port":"80"}}'
+ ```
- * **dashboard-cm**
-
- To enable AI integration via feature flag, check if the below entry is present in the ConfigMap (create one if it doesn't exist).
-
- ```yaml
- FEATURE_AI_INTEGRATION_ENABLE: "true"
- ```
+ | Key | Description |
+ |:---|:---|
+ | `FEATURE_ASK_DEVTRON_EXPERT` | Enables the **Ask Devtron Expert** chatbot (default `false`). |
+ | `PROXY_SERVICE_CONFIG` | Routes requests from the orchestrator to the Athena API server. Set `host` (and `port`) to the **`athena-api` Kubernetes Service** created by the chart in Step 2 — confirm the exact name and port with `kubectl get svc -n \| grep athena`. |
- 
-
Figure 6: Entry in 'dashboard-cm' ConfigMap
+* **dashboard-cm** — enable AI integration and (optionally) AI Debug Mode:
+ ```yaml
+ FEATURE_AI_INTEGRATION_ENABLE: "true"
+ FEATURE_ATHENA_DEBUG_MODE_ENABLE: "true"
+ ```
-### 6. Restart Pods
+ | Key | Description |
+ |:---|:---|
+ | `FEATURE_AI_INTEGRATION_ENABLE` | Master switch that enables the **Explain with AI** buttons across the UI. |
+ | `FEATURE_ATHENA_DEBUG_MODE_ENABLE` | When `true`, using **Explain with AI** opens the Holmes debugger as a new chat in the **Ask Devtron** side panel. When `false` (default), the AI response appears in a draggable widget. |
-1. Go to **Infrastructure Management** → **Resource Browser** → (Select Cluster) → **Workloads** → **Deployment**
+### 4. Restart and Hard Refresh
-2. Click the checkbox next to the following **Deployment** workloads and restart them using the **`⟳`** button:
+1. Go to **Infrastructure Management** → **Resource Browser** → (Select Cluster) → **Workloads** → **Deployment**, and restart the following using the **`⟳`** button so they pick up the ConfigMap changes:
* `devtron`
* `dashboard`
-
Figure 7: Restart 'devtron' and 'dashboard' deployment workloads
-
-
-### 7. Perform Hard Refresh
+
Figure 2: Restart 'devtron' and 'dashboard' deployment workloads
-Perform a hard refresh of the browser to clear the cache:
-* **Mac**: Hold down `Cmd` and `Shift` and then press `R`
-* **Windows/Linux**: Hold down `Ctrl` and then press `F5`
+2. Perform a hard refresh of the browser to clear the cache:
+ * **Mac**: Hold down `Cmd` and `Shift` and then press `R`
+ * **Windows/Linux**: Hold down `Ctrl` and then press `F5`
---
## Results
-Devtron supports **Explain** option at the following screens (only for specific scenarios where troubleshooting is possible through AI):
+Devtron supports the **Explain** option at the following screens (only for specific scenarios where troubleshooting is possible through AI):
### Pod Errors
**Path**: Infrastructure Management → Resource Browser → (Select Cluster) → Workloads → Pod
-
### Pod Last Restart Snapshot
**Path**: Infrastructure Management → Resource Browser → (Select Cluster) → Workloads → Pod → Pod Last Restart Snapshot
-
diff --git a/docs/user-guide/global-configurations/migrate-gitops-provider.md b/docs/user-guide/global-configurations/migrate-gitops-provider.md
new file mode 100644
index 0000000000..701715153d
--- /dev/null
+++ b/docs/user-guide/global-configurations/migrate-gitops-provider.md
@@ -0,0 +1,104 @@
+# Migrate GitOps Provider (API)
+
+Devtron provides APIs to migrate the GitOps configuration of your deployments from one Git provider to another — for example, from **GitHub to GitLab** (or to Bitbucket, Azure, an on-prem Git server, and so on).
+
+When you trigger a migration, Devtron clones the deployment manifests from the existing GitOps repository and pushes them to a repository on the **target** GitOps provider, then updates the affected deployments to use the new provider.
+
+:::info This is an API-only feature
+There is currently no dashboard UI for GitOps provider migration; it is performed through the REST APIs described below.
+:::
+
+## Prerequisites
+
+* The **target GitOps provider** must already be configured in **Global Configurations → GitOps**. Note its GitOps configuration `id` — you will pass it as `gitOpsProviderId`. (You can list configured providers via `GET /orchestrator/gitops/config`.)
+* The applications/charts you want to migrate must already be deploying through GitOps (`argo_cd` or `flux_cd`).
+
+## Authorization
+
+These APIs can only be called by a **super-admin**. Pass your auth token in the `token` header.
+
+## Endpoints
+
+| Method | Path | Description |
+|:---|:---|:---|
+| `POST` | `/orchestrator/migration/deploy` | Migrate the GitOps provider for a set of resources selected by project, environment, and/or application. |
+| `POST` | `/orchestrator/migration/deploy/app-level` | Perform the migration at the application level. Uses the same request body. |
+
+## Request Body
+
+Both endpoints accept the same JSON body:
+
+```json
+{
+ "selectors": [
+ {
+ "projectIds": [1],
+ "envIds": [2, 3],
+ "appIds": [10, 11],
+ "appType": "DevtronApp"
+ }
+ ],
+ "migrateTo": {
+ "deploymentAppType": "argo_cd",
+ "gitOpsProviderId": 4
+ },
+ "dryRun": true
+}
+```
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `selectors` | array | Scopes the migration. Each selector narrows the set of resources to migrate. |
+| `selectors[].projectIds` | array of int | Restrict to these project IDs. |
+| `selectors[].envIds` | array of int | Restrict to these environment IDs. |
+| `selectors[].appIds` | array of int | Restrict to these application IDs. |
+| `selectors[].appType` | string | `DevtronApp` (custom apps) or `DevtronChart` (Helm apps). |
+| `migrateTo` | object | The target deployment configuration. |
+| `migrateTo.deploymentAppType` | string | The GitOps deployment type of the apps being migrated — `argo_cd` or `flux_cd`. |
+| `migrateTo.gitOpsProviderId` | int | The `id` of the target GitOps provider to migrate to (from **Global Configurations → GitOps**). |
+| `dryRun` | boolean | When `true`, Devtron evaluates the migration and returns what *would* happen, **without** making any changes. Recommended before running a real migration. |
+
+## Response
+
+```json
+{
+ "message": "migration completed",
+ "details": [
+ {
+ "pipelineId": 25,
+ "pipelineName": "cd-1-abcd",
+ "appName": "my-app",
+ "envName": "production",
+ "appId": 10,
+ "envId": 2,
+ "currentConfig": {
+ "deploymentAppType": "argo_cd",
+ "gitOpsProviderId": 1
+ },
+ "status": "Success"
+ }
+ ]
+}
+```
+
+| Field | Type | Description |
+|:---|:---|:---|
+| `message` | string | Overall result message. |
+| `details` | array | Per-pipeline migration result. |
+| `details[].pipelineId` / `pipelineName` | int / string | The CD pipeline that was migrated. |
+| `details[].appName` / `appId` | string / int | The application. |
+| `details[].envName` / `envId` | string / int | The environment. |
+| `details[].currentConfig` | object | The deployment config (`deploymentAppType`, `gitOpsProviderId`) **before** migration. |
+| `details[].status` | string | Per-pipeline status of the migration. |
+
+## Recommended workflow
+
+1. Configure the target GitOps provider in **Global Configurations → GitOps** and note its `gitOpsProviderId`.
+2. Run the migration with **`"dryRun": true`** to preview which pipelines will be affected and validate the target configuration.
+3. Review the `details` in the response.
+4. Re-run the same request with **`"dryRun": false`** to perform the migration.
+5. Verify that the affected applications now point to the new provider's repositories and that subsequent deployments succeed.
+
+:::caution
+GitOps provider migration moves deployment manifests to repositories on the target provider. Run a dry run first, and migrate in batches (using `selectors`) rather than all applications at once, so you can verify each batch before proceeding.
+:::
diff --git a/docs/user-guide/global-configurations/scoped-variables.md b/docs/user-guide/global-configurations/scoped-variables.md
index e3b3f2e42c..5861e36157 100755
--- a/docs/user-guide/global-configurations/scoped-variables.md
+++ b/docs/user-guide/global-configurations/scoped-variables.md
@@ -361,4 +361,6 @@ There are some system variables that exist by default in Devtron that you can re
:::info
Currently, these variables do not appear in the scoped variable widget, but you may use them.
-:::
\ No newline at end of file
+:::
+
+You can reference a predefined variable the same way as any other scoped variable, using `@{{}}` — for example, `@{{DEVTRON_IMAGE}}`. When using it inside a deployment template, encapsulate it in double quotes: `"@{{DEVTRON_IMAGE}}"`.
\ No newline at end of file
diff --git a/docs/user-guide/resource-browser/scoop-config.md b/docs/user-guide/resource-browser/scoop-config.md
index d85f00da63..dc7b04541d 100644
--- a/docs/user-guide/resource-browser/scoop-config.md
+++ b/docs/user-guide/resource-browser/scoop-config.md
@@ -4,6 +4,18 @@
To enable **Pod Last Restart Snapshot**, you must configure Scoop in your target cluster. Scoop collects pod restart events from your cluster and sends them to Devtron, allowing the platform to display details such as restart reason, timestamp, and pre-restart logs directly in the Pod Listing view.
+## Capabilities
+
+Scoop runs as a lightweight service inside your target cluster and provides the following capabilities:
+
+* **Pod restart monitoring** — Tracks application pod restarts and surfaces details such as the restart reason, timestamp, previous-container logs, and node status in the Pod listing view. This powers the **Pod Last Restart Snapshot** feature.
+
+* **Event tracking** — Watches events across Kubernetes resources in the cluster, so you can observe and act on what is happening to your workloads.
+
+* **Resource caching** — Caches Kubernetes resources in the target cluster, reducing Kubernetes API fetch times when you browse resources in the **Resource Browser**. This capability is controlled per cluster by the `enableResourceList` flag (see [Update ConfigMap](#4-update-configmap)).
+
+* **Resource Watcher (auto-remediation)** — Scoop performs the in-cluster event watching that powers Devtron's [Resource Watcher](../resource-watcher.md). When you configure a watcher, Devtron registers it with the target cluster's Scoop instance, which intercepts the matching events and triggers the webhook or job you defined. As a result, the **Resource Watcher feature requires Scoop to be deployed in the target cluster**.
+
## Steps to Configure Scoop
### 1. Deploying Scoop Chart
@@ -127,7 +139,7 @@ The **orchestrator-cm** ConfigMap will be available only if you have Devtron man
| **"1" and "2"** | The cluster IDs of your clusters (as seen in the Resource Browser URL). Each ID represents a unique cluster where Scoop is deployed |
| **serviceName** | The name of the Scoop service you noted from the **Service** tab while checking the endpoint |
| **passKey** | The value of authentication key (`PASS_KEY`) that you defined (or left as default) during Scoop chart deployment |
- | **enableResourceList** | A flag that controls whether resource-level details are fetched. Keep it **false** unless you specifically need that data |
+ | **enableResourceList** | Enables Scoop's **resource caching** capability for this cluster. When `true`, the Resource Browser serves cached Kubernetes resources from Scoop (faster listing, fewer direct Kubernetes API calls). When `false` (default), resources are fetched directly from the cluster. This is a **per-cluster** flag — enable it only for the clusters where you want cached resource listing |
| **namespace** | The namespace of the Scoop service you noted from the **Service** tab while checking the endpoint |
| **port** | The port number of the Scoop service you noted from the **Service** tab while checking the endpoint |
diff --git a/sidebars.js b/sidebars.js
index 898cc6133c..14a35892cb 100755
--- a/sidebars.js
+++ b/sidebars.js
@@ -234,6 +234,7 @@ const sidebars = {
},
items: [
'user-guide/global-configurations/gitops',
+ 'user-guide/global-configurations/migrate-gitops-provider',
'user-guide/global-configurations/git-accounts',
'user-guide/global-configurations/external-links',
'user-guide/global-configurations/chart-repo',
@@ -12,306 +9,180 @@ Check out the [Results](#results) section to see where Devtron gives you AI-powe
