diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index b32433e52b..e0d2bcd3ac 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -34,6 +34,7 @@
* [Notifications](user-guide/global-configurations/manage-notification.md)
* [External Links](user-guide/global-configurations/external-links.md)
* [Scoped Variables](user-guide/global-configurations/scoped-variables.md)
+ * [Pull Image Digest](user-guide/global-configurations/pull-image-digest.md)
* [Tags Policy](user-guide/global-configurations/tags-policy.md)
* [Filter Condition](user-guide/global-configurations/filter-condition.md)
* [Devtron Upgrade](setup/upgrade/README.md)
diff --git a/docs/user-guide/creating-application/workflow/cd-pipeline.md b/docs/user-guide/creating-application/workflow/cd-pipeline.md
index e065628e64..47f7cef9cd 100644
--- a/docs/user-guide/creating-application/workflow/cd-pipeline.md
+++ b/docs/user-guide/creating-application/workflow/cd-pipeline.md
@@ -1,210 +1,252 @@
# CD Pipeline
-Once you are done creating your CI pipeline, you can start building your CD pipeline. Devtron enables you to design your CD pipeline in a way that fully automates your deployments.
+
+After your CI pipeline is ready, you can start building your CD pipeline. Devtron enables you to design your CD pipeline in a way that fully automates your deployments. Images from CI stage can be deployed to one or more environments through dedicated CD pipelines.
## Creating CD Pipeline
-
+Click the '**+**' sign on CI Pipeline to attach a CD Pipeline to it.
-Click on **“+”** sign on CI Pipeline to attach a CD Pipeline to it. A basic `Create deployment modal` will pop up.
+
-
+A basic `Create deployment pipeline` window will pop up.
-This section expects two inputs:
+
-* **Select Environment**
-* **Deployment Strategy**
+Here, you get three sections:
-### 1. Select Environment
-This section further includes two inputs:
+* [Deploy to Environment](#1-deploy-to-environment)
+* [Deployment Strategy](#2-deployment-strategy)
+* [Advanced Options](#3-advanced-options)
-**\(a\) Deploy to Environment**
+### 1. Deploy to Environment
-Select the environment where you want to deploy your application.
+This section expects three inputs from you:
-**\(b\) Namespace**
+| Setting | Description | Options |
+| ----------- | ---------------------------------------------------------- | ------------------------- |
+| Environment | Select the environment where you want to deploy your application | (List of available environments) |
+| Namespace | Automatically populated based on the selected environment | Not Applicable |
+| Trigger | When to execute the deployment pipeline | **Automatic**: Deployment triggers automatically when a new image completes the previous stage (build pipeline or another deployment pipeline)
**Manual**: Deployment is not initiated automatically. You can trigger deployment with a desired image. |
-This field will be automatically populated with the `Namespace` corresponding to the `Environment` selected in the previous step.
+### 2. Deployment Strategy
-Click on `Create Pipeline` to create a CD pipeline.
+Devtron supports multiple deployment strategies depending on the [deployment chart type](../../creating-application/deployment-template.md#select-chart-from-default-charts).
-> One can have a single CD pipeline or multiple CD pipelines connected to the same CI Pipeline. Each CD pipeline corresponds to only one environment, or in other words, any single environment of an application can have only one CD pipeline.
-So, the images created by the CI pipeline can be deployed into multiple environments through different CD pipelines originating from a single CI pipeline.
-If you already have one CD pipeline and want to add more, you can add them by clicking on the `+` sign and then choosing the environment in which you want to deploy your application. Once a new CD Pipeline is created for the environment of your choosing, you can move ahead and configure the CD pipeline as required.
-Your CD pipeline can be configured for the pre-deployment stage, the deployment stage, and the post-deployment stage. You can also select the deployment strategy of your choice. You can add your configurations as explained below:
+
+Refer [Deployment Strategies](#deployment-strategies) to know more about each strategy in depth.
-To configure the advanced CD option click **Advanced Options** at the bottom.
+{% hint style="info" %}
+The next section is [Advanced Options](#advanced-options) and it comes with additional capabilities. However, if you don't need them, you may proceed with a basic CD pipeline and click **Create Pipeline**.
+{% endhint %}
-
+### 3. Advanced Options
-| Key | Description |
-| :--- | :--- |
-| Pipeline Name | Enter the name of the pipeline to be created |
-| Environment | Select the environment in which you want to deploy |
-| Pre-deployment stage | Run any configuration and provide secrets before the deployment |
-| Deployment stage | Select how and when you want the deployment to be triggered - Automatic or manual triggering of your CD Pipeline |
-| Deployment Strategy | Select the type of deployment strategy that you want to enable by clicking `Add Deployment Strategy` |
-| Post-deployment stage | If you need to run any configurations and provide secrets after the deployment, mention those here |
+This option is available at the bottom of the `Create deployment pipeline` window.
+
-### 1. Pipeline Name
+Now, the window will have 3 distinct tabs, and you will see the following additions:
+* [Pre-Deployment stage (tab)](#pre-deployment-stage)
+* [Deployment stage (tab)](#deployment-stage)
+ * [Pipeline Name (input field)](#pipeline-name)
+ * [Manual approval for deployment (toggle button)](#manual-approval-for-deployment)
+ * [Custom Image tag pattern (toggle button)](#custom-image-tag-pattern)
+ * [Pull container image with image digest](#pull-container-image-with-image-digest)
+* [Post-Deployment stage (tab)](#post-deployment-stage)
-Pipeline name will be autogenerated.
+
-### 2. Deploy to Environment
+{% hint style="info" %}
+You can create or edit a deployment strategy in Advanced Options. Remember, only the default strategy will be used for deployment, so use the **SET DEFAULT** button to mark your preferred strategy as default after creating it.
+{% endhint %}
-As we discussed above, Select the environment where you want to deploy your application. Once you select the environment, it will display the `Namespace` corresponding to your selected environment automatically.
+#### Pre-Deployment Stage
-## Stages
-There are 3 dropdowns given below:
+If your deployment requires prior actions like DB migration, code quality check (QC), etc., you can use the `Pre-deployment stage` to configure such tasks.
-* **Pre-deployment stage**
-* **Deployment stage**
-* **Post-deployment stage**
+
-### 3. Pre-deployment stage
+1. **Tasks**
-Sometimes one has a requirement where certain actions like DB migration are to be executed before deployment, the `Pre-deployment stage` should be used to configure these actions.
+Here you can add one or more tasks. The tasks can be re-arranged using drag-and-drop and they will be executed sequentially.
-Pre-deployment stages can be configured to be executed automatically or manually.
+2. **Trigger Pre-Deployment Stage**
-If you select automatic, `Pre-deployment Stage` will be triggered automatically after the CI pipeline gets executed and before the CD pipeline starts executing itself. But, if you select a manual, then you have to trigger your stage via console.
+Refer the trigger types from [here](#1-deploy-to-environment).
-If you want to use some configuration files and secrets in pre-deployment stages or post-deployment stages, then you can use the `Config Maps` & `Secrets` options.
+3. **ConfigMaps & Secrets**
-`Config Maps` can be used to define configuration files. And `Secrets` can be defined to store the private data of your application.
+{% hint style="info" %}
+### Prerequisites
+Make sure you have added [ConfigMaps](../config-maps.md) and [Secrets](../secrets.md) in App Configuration.
+{% endhint %}
-Once you are done defining Config Maps & Secrets, you will get them as a drop-down in the pre-deployment stage and you can select them as part of your pre-deployment stage.
+If you want to use some configuration files and secrets in pre-deployment stages or post-deployment stages, then you can use the `ConfigMaps` & `Secrets` options. You will get them as a drop-down in the pre-deployment stage.
-These `Pre-deployment CD / Post-deployment CD` pods can be created in your deployment cluster or the devtron build cluster. It is recommended that you run these pods in the Deployment cluster so that your scripts \(if there are any\) can interact with the cluster services that may not be publicly exposed.
+4. **Execute tasks in application environment**
-If you want to run it inside your application, then you have to check the `Execute in application Environment` option else leave it unchecked to run it within the Devtron build cluster.
+These `Pre-deployment CD / Post-deployment CD` pods can be created in your deployment cluster or the devtron build cluster. If your scripts/tasks has some dependency on the deployment environment, you may run these pods in the deployment cluster. Thus, your scripts \(if any\) can interact with the cluster services that may not be publicly exposed.
-Make sure your cluster has `devtron-agent` installed if you check the `Execute in the application Environment` option.
+Some tasks require extra permissions for the node where Devtron is installed. However, if the node already has the necessary permissions for deploying applications, there is no need to assign them again. Instead, you can enable the **Execute tasks in application environment** option for the pre-CD or post-CD steps. By default, this option is disabled.
-
+To enable the `Execute tasks in application environment` option, follow these steps:
-### 4. Manual approval for deployment
+{% hint style="info" %}
+Make sure your cluster has [devtron-agent](../../global-configurations/cluster-and-environments.md#installing-devtron-agent) installed.
+{% endhint %}
-When `Manual approval for deployment` is enabled, only approved images are available for deployment through the respective deployment pipeline.
-Users can specify the number of approvals required for each deployment, where the permissible limit ranges from one approval (minimum) to six approval (maximum).
+* Go to the chart store and search for the devtron-in-clustercd chart.
-
+ 
-To enable manual approval for deployment, follow these steps:
+* Configure the chart according to your requirements and deploy it in the target cluster.
-1. Click the deployment pipeline for which you want to enable manual approval.
-2. Turn on the ‘Manual approval for deployment’ toggle button.
-3. Select the number of approvals required for each deployment.
+* After the deployment, edit the devtron-cm configmap and add the following key-value pair:
-### 5. Deployment stage
+ ```bash
+ ORCH_HOST: /orchestrator/webhook/msg/nats
-**\(a\) Deploy to Environment**
+ Example:
-Select the environment where you want to deploy your application. Once you select the environment, it will display the `Namespace` corresponding to your selected environment automatically.
+ ORCH_HOST: http://xyz.devtron.com/orchestrator/webhook/msg/nats
-**\(b\)We support two methods of deployments** - Manual and Automatic. If you choose automatic, it will trigger your CD pipeline automatically once the corresponding CI pipeline has been executed successfully.
+ ```
-If you have defined pre-deployment stages, then the CD Pipeline will be triggered automatically after the successful execution of your CI pipeline followed by the successful execution of your pre-deployment stages. But if you choose the manual option, then you have to trigger your deployment manually via console.
+ `ORCH_HOST` value should be same as of `CD_EXTERNAL_LISTENER_URL` value which is passed in values.yaml.
-**\(c\) Deployment Strategy**
+ 
-Devtron's tool has 4 types of deployment strategies. Click on `Add Deployment strategy` and select from the available options:
+* Delete the Devtron pod using the following command:
-\(a\) Recreate
+ ```bash
+ kubectl delete pod -l app=devtron -n devtroncd
+ ```
-\(b\) Canary
+* Again navigate to the chart store and search for the "migration-incluster-cd" chart.
-\(c\) Blue Green
+ 
-\(d\) Rolling
+* Edit the `cluster-name` and `secret name` values within the chart. The `cluster name` refers to the name used when adding the cluster in the global configuration and for which you are going to enable `Execute tasks in application environment` option.
-### 6. Post-deployment Stage
+ 
-If you want to run actions like closure of Jira ticket after the deployment, you can configure such actions in the post-deployment stages.
+* Deploy the chart in any environment within the Devtron cluster. Now you should be able to enable `Execute tasks in application environment` option for an environment of target cluster.
-Post-deployment stages are similar to pre-deployment stages. The difference is, pre-deployment executes before the CD pipeline execution and post-deployment executes after the CD pipeline execution. The configuration of post-deployment stages is similar to the pre-deployment stages.
+#### Deployment Stage
-You can use Config Map and Secrets in post deployments as well, as defined in the Pre-Deployment stages.
+##### Pipeline Name
-
+Pipeline name will be auto-generated; however, you are free to modify the name as per your requirement.
+##### Manual Approval for Deployment [](https://devtron.ai/pricing)
-Once you have configured the CD pipeline, click on `Create Pipeline` to save it. You can see your newly created CD Pipeline on the Workflow tab attached to the corresponding CI Pipeline.
+If you want only approved images to be eligible for deployment, enable the `Manual approval for deployment` option in the respective deployment pipeline. By doing so, unapproved images would be prevented from being deployed for that deployment pipeline.
+{% hint style="info" %}
+Currently, only super-admins can enable or disable this option.
+{% endhint %}
-### 7. Execute in Application Environment
+Users can also specify the number of approvals required for each deployment, where the permissible limit ranges from one approval (minimum) to six approvals (maximum). In other words, if the image doesn't get the specified number of approvals, it will not be eligible for deployment
-When deploying an application, we often need to perform additional tasks before or after the deployments. These tasks require extra permissions for the node where Devtron is installed. However, if the node already has the necessary permissions for deploying applications, there is no need to assign them again. Instead, you can enable the "Execute in application environment" option for the pre-CD and post-CD steps. By default, this option is disabled, and some configurations are required to enable it.
+
-To enable the "Execute in application environment" option, follow these steps:
+To enable manual approval for deployment, follow these steps:
-1. Go to the chart store and search for the devtron-in-clustercd chart.
+1. Click the deployment pipeline for which you want to enable manual approval.
+2. Turn on the ‘Manual approval for deployment’ toggle button.
+3. Select the number of approvals required for each deployment.
-
+To know more about the approval process, refer [Triggering CD](../../deploying-application/triggering-cd.md#manual-approval-for-deployment).
-2. Configure the chart according to your requirements and deploy it in the target cluster.
-3. After the deployment, edit the devtron-cm configmap and add the following key-value pair:
+##### Custom Image Tag Pattern
-```bash
-ORCH_HOST: /orchestrator/webhook/msg/nats
+{% hint style="warning" %}
+This will be utilized only when an existing container image is copied to another repository using the [Copy Container Image Plugin](../workflow/plugins/copy-container-image.md). The image will be copied with the tag generated by the Image Tag Pattern you defined.
+{% endhint %}
-Example:
+1. Enable the toggle button as shown below.
-ORCH_HOST: http://xyz.devtron.com/orchestrator/webhook/msg/nats
+ 
-```
-`ORCH_HOST` value should be same as of `CD_EXTERNAL_LISTENER_URL` value which is passed in values.yaml.
+2. Click the edit icon.
-
+ 
+3. You can write an alphanumeric pattern for your image tag, e.g., **prod-v1.0.{x}**. Here, 'x' is a mandatory variable whose value will incrementally increase with every pre or post deployment trigger (that option is also available to you). You can also define the value of 'x' for the next trigger in case you want to change it.
+ 
-4. Delete the Devtron pod using the following command:
+ {% hint style="warning" %}
+ Ensure your custom tag do not start or end with a period (.) or comma (,)
+ {% endhint %}
-```bash
-kubectl delete pod -l app=devtron -n devtroncd
-```
+4. Click **Update Pipeline**.
-5. Again navigate to the chart store and search for the "migration-incluster-cd" chart.
+To know how and where this image tag would appear, refer [Copy Container Image Plugin](../workflow/plugins/copy-container-image.md)
-
+##### Pull Container Image with Image Digest
-6. Edit the `cluster-name` and `secret name` values within the chart. The `cluster name` refers to the name used when adding the cluster in the global configuration and for which you are going to enable `Execute in application environment` option.
+Although Devtron ensures that [image tags](#custom-image-tag-pattern) remain unique, the same cannot be said if images are pushed with the same tag to the same container registry from outside Devtron.
-
+Therefore, to eliminate the possibility of pulling an unintended image, Devtron offers the option to pull container images using digest and image tag.
-7. Deploy the chart in any environment within the Devtron cluster.
+
-Now you should be able to enable `Execute in application environment` option for an environment of target cluster.
+An image digest is a unique and immutable SHA-256 string returned by the container registry when you push an image. So the image referenced by the digest will never change.
-
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have Admin permission or above (along with access to the environment and application) to enable this option. However, this option will be non-editable in case the super-admin has enabled [pull image digest in Global Configurations](../../global-configurations/pull-image-digest.md).
+{% endhint %}
-## Update CD Pipeline
+#### Post-Deployment Stage
-You can update the deployment stages and the deployment strategy of the CD Pipeline whenever you require it. But, you cannot change the name of a CD Pipeline or its Deployment Environment. If you need to change such configurations, you need to make another CD Pipeline from scratch.
+If you need to run any actions for e.g., closure of Jira ticket, load testing or performance testing, you can configure such actions in the post-deployment stages.
-To Update a CD Pipeline, go to the `App Configurations` section, Click on `Workflow editor` and then click on the CD Pipeline you want to Update.
+Post-deployment stages are similar to pre-deployment stages. The difference is, pre-deployment executes before the deployment, while post-deployment occurs after.
-
+You can use [ConfigMap and Secrets](#configmaps--secrets) in post deployments as well. The option to execute tasks in application environment is available too.
+
+
+
+---
+
+## Updating CD Pipeline
+
+You can update the deployment stages and the deployment strategy of the CD Pipeline whenever you require it. However, you cannot change the name of a CD Pipeline or its Deployment Environment. If you want a new CD pipeline for the same environment, first delete the previous CD pipeline.
+
+To update a CD Pipeline, go to the `App Configurations` section, Click on `Workflow editor` and then click on the CD Pipeline you want to Update.
+
+
Make changes as needed and click on `Update Pipeline` to update this CD Pipeline.
-## Delete CD Pipeline
+---
-If you no longer require the CD Pipeline, you can also Delete the Pipeline.
+## Deleting CD Pipeline
-To Delete a CD Pipeline, go to the App Configurations and then click on the Workflow editor. Now click on the pipeline you want to delete. A pop will be displayed with CD details. Verify the name and the details to ensure that you are not accidentally deleting the wrong CD pipeline and then click on the Delete Pipeline option to delete the CD Pipeline.
+If you no longer require the CD Pipeline, you can also delete the Pipeline.
+To delete a CD Pipeline, go to the App Configurations and then click on the Workflow editor. Now click on the pipeline you wish to delete. A pop-up having the CD details will appear. Verify the name and the details to ensure that you are not accidentally deleting the wrong CD pipeline and then click **Delete Pipeline** to delete it.
-## Deployment Strategies
+{% hint style="warning" %}
+Deleting a CD pipeline also deletes all the K8s resources associated with it and will bring a disruption in the deployed micro-service. Before deleting a CD pipeline, please ensure that the associated resources are not being used in any production workload.
+{% endhint %}
-A deployment strategy is a way to make changes to an application, without downtime in a way that the user barely notices the changes. There are different types of deployment strategies like Blue/green Strategy, Rolling Strategy, Canary Strategy, Recreate Strategy. These deployment configuration-based strategies are discussed in this section.
+---
-**Blue Green Strategy**
+## Extras
+
+### Deployment Strategies
+
+A deployment strategy is a method of updating, downgrading, or creating new versions of an application. The options you see under deployment strategy depend on the selected chart type (see fig 2). Below are some deployment configuration-based strategies.
+
+#### 1. Blue-Green Strategy
Blue-green deployments involve running two versions of an application at the same time and moving traffic from the in-production version \(the green version\) to the newer version \(the blue version\).
@@ -219,11 +261,11 @@ blueGreen:
| Key | Description |
| :--- | :--- |
| `autoPromotionSeconds` | It will make the rollout automatically promote the new ReplicaSet to active Service after this time has passed |
-| `scaleDownDelaySeconds` | It is used to delay scaling down the old ReplicaSet after the active Service is switched to the new ReplicaSet. |
+| `scaleDownDelaySeconds` | It is used to delay scaling down the old ReplicaSet after the active Service is switched to the new ReplicaSet |
| `previewReplicaCount` | It will indicate the number of replicas that the new version of an application should run |
-| `autoPromotionEnabled` | It will make the rollout automatically promote the new ReplicaSet to the active service. |
+| `autoPromotionEnabled` | It will make the rollout automatically promote the new ReplicaSet to the active service |
-**Rolling Strategy**
+#### 2. Rolling Strategy
A rolling deployment slowly replaces instances of the previous version of an application with instances of the new version of the application. Rolling deployment typically waits for new pods to become ready via a readiness check before scaling down the old components. If a significant issue occurs, the rolling deployment can be aborted.
@@ -235,10 +277,10 @@ rolling:
| Key | Description |
| :--- | :--- |
-| `maxSurge` | No. of replicas allowed above the scheduled quantity. |
-| `maxUnavailable` | Maximum number of pods allowed to be unavailable. |
+| `maxSurge` | No. of replicas allowed above the scheduled quantity |
+| `maxUnavailable` | Maximum number of pods allowed to be unavailable |
-**Canary Strategy**
+#### 3. Canary Strategy
Canary deployments are a pattern for rolling out releases to a subset of users or servers. The idea is to first deploy the change to a small subset of servers, test it, and then roll the change out to the rest of the servers. The canary deployment serves as an early warning indicator with less impact on downtime: if the canary deployment fails, the rest of the servers aren't impacted.
@@ -263,23 +305,27 @@ canary:
| `maxSurge` | It defines the maximum number of replicas the rollout can create to move to the correct ratio set by the last setWeight |
| `maxUnavailable` | The maximum number of pods that can be unavailable during the update |
| `setWeight` | It is the required percent of pods to move to the next step |
-| `duration` | It is used to set the duration to wait to move to the next step. |
+| `duration` | It is used to set the duration to wait to move to the next step |
-**Recreate**
+#### 4. Recreate Strategy
-The recreate strategy is a dummy deployment that consists of shutting down version A then deploying version B after version A is turned off. A recreate deployment incurs downtime because, for a brief period, no instances of your application are running. However, your old code and new code do not run at the same time.
+The recreate strategy is a dummy deployment that consists of shutting down version 'A' and then deploying version 'B' after version 'A' is turned off.
+
+A recreate deployment incurs downtime because, for a brief period, no instances of your application are running. However, your old code and new code do not run at the same time. It terminates the old version and releases the new one.
```markup
recreate:
```
-It terminates the old version and releases the new one.
+Unlike other strategies mentioned above, 'Recreate' strategy doesn't contain keys for you to configure.
-[Does your app has different requirements in different Environments? Also read Environment Overrides](../environment-overrides.md)
+{% hint style="info" %}
+Does your app have different requirements for different environments? Read [Environment Overrides](../environment-overrides.md)
+{% endhint %}
-## Creating Sequential Pipelines
+### Creating Sequential Pipelines
-Devtron now supports attaching multiple deployment pipelines to a single build pipeline, in its workflow editor. This feature lets you deploy an image first to stage, run tests and then deploy the same image to production.
+Devtron supports attaching multiple deployment pipelines to a single build pipeline, in its workflow editor. This feature lets you deploy an image first to stage, run tests and then deploy the same image to production.
Please follow the steps mentioned below to create sequential pipelines:
@@ -287,6 +333,7 @@ Please follow the steps mentioned below to create sequential pipelines:
2. To add another CD Pipeline sequentially after previous one, again click on + sign on the last CD pipeline.
3. Similarly, you can add multiple CD pipelines by clicking + sign of the last CD pipeline, each deploying in different environments.
-
+
+
+
-> Note: Deleting a CD pipeline also deletes all the K8s resources associated with it and will bring a disruption in the deployed micro-service. Before deleting a CD pipeline, please ensure that the associated resources are not being used in any production workload.
diff --git a/docs/user-guide/creating-application/workflow/ci-pipeline.md b/docs/user-guide/creating-application/workflow/ci-pipeline.md
index 7da88d0c85..8d924551dd 100644
--- a/docs/user-guide/creating-application/workflow/ci-pipeline.md
+++ b/docs/user-guide/creating-application/workflow/ci-pipeline.md
@@ -1,30 +1,36 @@
# CI Pipeline
-> **Note:**
->
-> For Devtron version older than v0.4.0, please refer the [CI Pipeline (legacy)](./ci-pipeline-legacy.md) page.
+{% hint style="info" %}
+For Devtron version older than v0.4.0, please refer the [CI Pipeline (legacy)](./ci-pipeline-legacy.md) page.
+{% endhint %}
+
+## Creating CI Pipeline
A CI Workflow can be created in one of the following ways:
* [Build and Deploy from Source Code](#1.-build-and-deploy-from-source-code)
* [Linked Build Pipeline](#2.-linked-build-pipeline)
* [Deploy Image from External Service](#3.-deploy-image-from-external-service)
+* Sync with Environment
+* Create a Job
+
+
-
+
Each method has different use-cases that can be tailored according the needs of the organization.
-## 1. Build and Deploy from Source Code
+### 1. Build and Deploy from Source Code
`Build and Deploy from Source Code` workflow allows you to build the container image from a source code repository.
1. From the **Applications** menu, select your application.
2. On the **App Configuration** page, select **Workflow Editor**.
3. Select **+ New Workflow**.
-4. Select **Build and deploy from source code**.
-5. Enter the following fields on the **Create build pipeline** screen:
+4. Select **Build and Deploy from Source Code**.
+5. Enter the following fields on the **Create build pipeline** window:
-
+
| Field Name | Required/Optional | Description |
| :--- | :--- | :--- |
@@ -32,31 +38,23 @@ Each method has different use-cases that can be tailored according the needs of
| Branch Name | Required | Branch that triggers the CI build |
| Advanced Options | Optional | Create Pre-Build, Build, and Post-Build tasks |
-### Advanced Options
-
-The advanced CI Pipeline includes the following stages:
-
-* Pre-build stage: The tasks in this stage run before the image is built.
-* Build stage: In this stage, the build is triggered from the source code that you provide.
-* Post-build stage: The tasks in this stage are triggered once the build is complete.
+#### Advanced Options
-The Pre-Build and Post-Build stages allow you to create Pre/Post-Build CI tasks as explained [here](./ci-build-pre-post-plugins.md).
+The Advanced CI Pipeline includes the following stages:
-### Scan for vulnerabilities
+* **Pre-build stage**: The tasks in this stage are executed before the image is built.
+* **Build stage**: In this stage, the build is triggered from the source code that you provide.
+* **Post-build stage**: The tasks in this stage will be triggered once the build is complete.
-To Perform the security scan after the container image is built, enable the **Scan for vulnerabilities** toggle in the build stage.
+
-
+The Pre-build and Post-build stages allow you to create Pre/Post-Build CI tasks as explained [here](./ci-build-pre-post-plugins.md).
+#### Build Stage
-### Build stage
+Go to the **Build stage** tab.
-The Build stage allows you to configure a build pipeline from the source code.
-
-1. From the **Create build pipeline** screen, select **Advanced Options**.
-2. Select **Build stage**.
-
-
+
| Field Name | Required/Optional | Description |
| :--- | :--- | :--- |
@@ -66,64 +64,37 @@ The Build stage allows you to configure a build pipeline from the source code.
| Branch Name | Required | Branch that triggers the CI build |
| Docker build arguments | Optional | Override docker build configurations for this pipeline.
- Key: Field name
- Value: Field value
-Select **Update Pipeline**.
+##### Source type
-### Source type: Branch Fixed
+###### Branch Fixed
-The **Source type** - "Branch Fixed" allows you to trigger a CI build whenever there is a code change on the specified branch.
+This allows you to trigger a CI build whenever there is a code change on the specified branch.
-Select the **Source type** as "Branch Fixed" and enter the **Branch Name**.
+Enter the **Branch Name** of your code repository.
-### Source type: Branch Regex
+###### Branch Regex
`Branch Regex` allows users to easily switch between branches matching the configured Regex before triggering the build pipeline.
In case of `Branch Fixed`, users cannot change the branch name in ci-pipeline unless they have admin access for the app. So, if users with
`Build and Deploy` access should be allowed to switch branch name before triggering ci-pipeline, `Branch Regex` should be selected as source type by a user with Admin access.
-
+
For example if the user sets the Branch Regex as `feature-*`, then users can trigger from branches such as `feature-1450`, `feature-hot-fix` etc.
-### Configuring Webhook
-
-> **Info**:
-> If you choose "Pull Request" or "Tag Creation" as the source type, you must first configure the Webhook for GitHub/Bitbucket as a prerequisite step.
-
-#### 1. Configure Webhook for GitHub
-
-1. Go to the **Settings** page of your repository and select **Webhooks**.
-2. Select **Add webhook**.
-3. In the **Payload URL** field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in Devtron the dashboard.
-4. Change the Content-type to `application/json`.
-5. In the **Secret** field, enter the secret from Devtron the dashboard when you select the source type as "Pull Request" or "Tag Creation".
-
-
+###### Pull Request
-6. Under **Which events would you like to trigger this webhook?**, select **Let me select individual events.** to trigger the webhook to build CI Pipeline.
-7. Select **Branch or tag creation** and **Pull Requests**.
-8. Select **Add webhook**.
+This allows you to trigger the CI build when a pull request is created in your repository.
-#### 2. Configure Webhook for Bitbucket cloud
+{% hint style="info" %}
+**Prerequisites**
-1. Go to the **Repository settings** page of your Bitbucket repository.
-2. Select **Webhooks** and then select **Add webhook**.
+[Configure the webhook](#configuring-webhook) for either GitHub or Bitbucket.
+{% endhint %}
-
-
-3. Enter a **Title** for the webhook.
-4. In the **URL** field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in the Devtron dashboard.
-5. Select the event triggers for which you want to trigger the webhook.
-6. Select **Save** to save your configurations.
-
-
-
-### Source type: Pull Request
-
-The **Source type** - "Pull Request" allows you to configure the CI Pipeline using the PR raised in your repository.
-
-> Before you begin, [configure the webhook](#configuring-webhook) for either GitHub or Bitbucket.
-
-> The "Pull Request" source type feature only works for the host GitHub or Bitbucket cloud for now. To request support for a different Git host, please create a github issue [here](https://github.com/devtron-labs/devtron/issues).
+{% hint style="warning" %}
+The **Pull Request** source type feature only works for the host GitHub or Bitbucket Cloud for now. To request support for a different Git host, please create a GitHub issue [here](https://github.com/devtron-labs/devtron/issues).
+{% endhint %}
@@ -145,11 +116,15 @@ Select the appropriate filter and pass the matching condition as a regular expre
Select **Create Pipeline**.
-### Source type: Tag Creation
+###### Tag Creation
+
+This allows you to trigger the CI build whenever a new tag is created.
-The **Source type** - "Tag Creation" allows you to build the CI pipeline from a tag.
+{% hint style="info" %}
+**Prerequisites**
-> Before you begin, [configure the webhook](#configuring-webhook) for either GitHub or Bitbucket.
+[Configure the webhook](#configuring-webhook) for either GitHub or Bitbucket.
+{% endhint %}
@@ -164,16 +139,70 @@ Select the appropriate filter and pass the matching condition as a regular expre
Select **Create Pipeline**.
-> **Note**
->
-> **(a)** You can provide pre-build and post-build stages via the Devtron tool’s console or can also provide these details by creating a file `devtron-ci.yaml`
-> inside your repository. There is a pre-defined format to write this file. And we will run these stages using this YAML file.
-> You can also provide some stages on the Devtron tool’s console and some stages in the devtron-ci.yaml file. But stages defined through the `Devtron` dashboard are
-> first executed then the stages defined in the `devtron-ci.yaml` file.
->
-> **(b)** The total timeout for the execution of the CI pipeline is by default set as 3600 seconds. This default timeout is configurable according to the use case. The timeout can be edited in the configmap of the orchestrator service in the env variable as `env:"DEFAULT_TIMEOUT" envDefault:"3600"`
+{% hint style="info" %}
+The total timeout for the execution of the CI pipeline is by default set as 3600 seconds. This default timeout is configurable according to the use case (refer [Build Infra](https://docs.devtron.ai/global-configurations/build-infra)).
+{% endhint %}
+
+##### Scan for Vulnerabilities
+
+{% hint style="info" %}
+### Prerequisite
+Install any one of the following integrations from Devtron Stack Manager:
+* [Clair](../../../user-guide/integrations/clair.md)
+* Trivy
+{% endhint %}
+
+To perform the security scan after the container image is built, enable the **Scan for vulnerabilities** toggle in the build stage. Refer [Security features](../../../user-guide/security-features.md) to know more.
+
+
+
+##### Custom Image Tag Pattern
+
+This feature helps you apply custom tags (e.g., `v1.0.0`) to readily distinguish container images within your repository.
+
+1. Enable the toggle button as shown below.
+
+ 
+
+2. You can write an alphanumeric pattern for your image tag, e.g., **test-v1.0.{x}**. Here, 'x' is a mandatory variable whose value will incrementally increase with every build. You can also define the value of 'x' for the next build trigger in case you want to change it.
+
+ 
+
+ {% hint style="warning" %}
+ Ensure your custom tag do not start or end with a period (.) or comma (,)
+ {% endhint %}
+
+3. Click **Update Pipeline**.
+
+4. Now, go to **Build & Deploy** tab of your application, and click **Select Material** in the CI pipeline.
+
+ 
+
+5. Choose the git commit you wish to use for building the container image. Click **Start Build**.
+
+ 
-## 2. Linked Build Pipeline
+6. The build will initiate and once it is successful the image tag would reflect at all relevant screens:
+
+ * **Build History**
+
+ 
+
+ * **Docker Registry**
+
+ 
+
+ * **CD Pipeline (Image Selection)**
+
+ 
+
+
+{% hint style="info" %}
+Build will fail if the resulting image tag has already been built in the past. This means if there is an existing image with tag `test-v1.0.0`, you cannot build another image having the same tag `test-v1.0.0` in the same CI pipeline. This error might occur when you reset the value of the variable `x` or when you disable/enable the toggle button for `Custom image tag pattern`.
+{% endhint %}
+
+
+### 2. Linked Build Pipeline
If one code is shared across multiple applications, `Linked Build Pipeline` can be used, and only one image will be built for multiple applications because if there is only one build, it is not advisable to create multiple CI Pipelines.
@@ -194,7 +223,7 @@ Click **Create Linked CI Pipeline**.
After creating a linked CI pipeline, you can create a CD pipeline.
Builds cannot be triggered from a linked CI pipeline; they can only be triggered from the source CI pipeline. There will be no images to deploy in the CD pipeline created from the 'linked CI pipeline' at first. To see the images in the CD pipeline of the linked CI pipeline, trigger build in the source CI pipeline. The build images will now be listed in the CD pipeline of the 'linked CI pipeline' whenever you trigger a build in the source CI pipeline.
-## 3. Deploy Image from External Service
+### 3. Deploy Image from External Service
For CI pipeline, you can receive container images from an external services via webhook API.
@@ -207,17 +236,13 @@ You can use Devtron for deployments on Kubernetes while using an external CI too
* On the `Base Deployment Template` page, select the `Chart type` from the drop-down list and configure as per your [requirements](https://docs.devtron.ai/usage/applications/creating-application/deployment-template) and click **Save & Next**.
* On the **Workflow Editor** page, click **New Workflow** and select **Deploy image from external service**.
-
-
-
-
* On the **Deploy image from external source** page, provide the information in the following fields:
-
+
| Fields | Description |
| --- | --- |
-| **Deploy to environment** | - `Environment`: Provide the name of the [environment](https://docs.devtron.ai/global-configurations/cluster-and-environments#add-environment).
- `Namespace`: Provide the [namespace](https://docs.devtron.ai/global-configurations/cluster-and-environments#add-environment).
|
+| **Deploy to environment** | - `Environment`: Provide the name of the [environment](../../global-configurations/cluster-and-environments#add-environment).
- `Namespace`: Provide the [namespace](../../global-configurations/cluster-and-environments#add-environment).
|
| **When do you want to deploy** | You can deploy either in one of the following ways: - `Automatic`: If you select automatic, your application will be deployed automatically everytime a new image is received.
- `Manual`: In case of manual, you have to select the image and deploy manually.
|
| **Deployment Strategy** | Configure the deployment preferences for this pipeline. |
@@ -225,25 +250,24 @@ You can use Devtron for deployments on Kubernetes while using an external CI too
A new CI pipeline will be created for the external source.
To get the webhook URL and JSON sample payload to be used in external CI pipeline, click **Show webhook details**.
-
+
* On the **Webhook Details** page, you have to authenticate via `API token` to allow requests from an external service (e.g. Jenkins or CircleCI).
* For authentication, only users with `super-admin` permissions can select or generate an API token:
- * You can either use **Select API Token** if you have generated an [API Token](https://docs.devtron.ai/getting-started/global-configurations/authorization/api-tokens) under **Global Configurations**.
-
- 
+ * You can either use **Select API Token** if you have generated an [API Token](../../global-configurations/authorization/api-tokens) under **Global Configurations**.
+ 
* Or use **Auto-generate token** to generate the API token with the required permissions. Make sure to enter the token name in the **Token name** field.
- 
+ 
* To allow requests from the external source, you can request the API by using:
* **Webhook URL**
* **cURL Request**
-### Webhook URL
+#### Webhook URL
HTTP Method: `POST`
@@ -261,7 +285,7 @@ You can also select metadata to send to Devtron. Sample JSON will be generated a
You can send the Payload script to your CI tools such as Jenkins and Devtron will receive the build image every time the CI pipeline is triggered or you can use the Webhook URL, which will build an image every time CI pipeline is triggered using Devtron Dashboard.
-### Sample cURL Request
+#### Sample cURL Request
```bash
curl --location --request POST \
@@ -273,7 +297,7 @@ curl --location --request POST \
}'
```
-### Response Codes
+#### Response Codes
| Code | Description |
| --- | --- |
@@ -282,17 +306,17 @@ curl --location --request POST \
| `401` | `Unauthorized` |
-### Integrate with External Sources - Jenkins or CircleCI
+#### Integrate with External Sources - Jenkins or CircleCI
* On the Jenkins dashboard, select the Jenkins job which you want to integrate with the Devtron dashboard.
* Go to the **Configuration** > **Build Steps**, click **Add build step**, and then click **Execute Shell**.
- 
+ 
* Enter the cURL request command.
* Make sure to enter the `API token` and `dockerImage` in your cURL command and click **Save**.
- 
+ 
Now, you can access the images on the Devtron dashboard and deploy manually. In case, if you select **Automatic** deployment option, then your application will be deployed automatically everytime a new image is received.
@@ -301,20 +325,62 @@ curl --location --request POST \
* Select the job on the `CircleCI` dashboard and click `Configuration File`.
* On the respective job, enter the `cURL` command and update the `API token` and `dockerImage` in your cURL command.
+---
-
-
-
-## Update CI Pipeline
+## Updating CI Pipeline
You can update the configurations of an existing CI Pipeline except for the pipeline's name.
To update a pipeline, select your CI pipeline.
In the **Edit build pipeline** window, edit the required stages and select **Update Pipeline**.
-
+
+
+---
-## Delete CI Pipeline
+## Deleting CI Pipeline
You can only delete a CI pipeline if there is no CD pipeline created in your workflow.
To delete a CI pipeline, go to **App Configurations > Workflow Editor** and select **Delete Pipeline**.
+
+
+
+
+
+---
+
+## Extras
+
+### Configuring Webhook
+
+{% hint style="info" %}
+If you choose [Pull Request](#pull-request) or [Tag Creation](#tag-creation) as the [source type](#source-type), you must first configure the Webhook for GitHub/Bitbucket as a prerequisite step.
+{% endhint %}
+
+#### For GitHub
+
+1. Go to the **Settings** page of your repository and select **Webhooks**.
+2. Select **Add webhook**.
+3. In the **Payload URL** field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in Devtron the dashboard.
+4. Change the Content-type to `application/json`.
+5. In the **Secret** field, enter the secret from Devtron the dashboard when you select the source type as "Pull Request" or "Tag Creation".
+
+
+
+6. Under **Which events would you like to trigger this webhook?**, select **Let me select individual events.** to trigger the webhook to build CI Pipeline.
+7. Select **Branch or tag creation** and **Pull Requests**.
+8. Select **Add webhook**.
+
+#### For Bitbucket Cloud
+
+1. Go to the **Repository settings** page of your Bitbucket repository.
+2. Select **Webhooks** and then select **Add webhook**.
+
+
+
+3. Enter a **Title** for the webhook.
+4. In the **URL** field, enter the Webhook URL that you get on selecting the source type as "Pull Request" or "Tag Creation" in the Devtron dashboard.
+5. Select the event triggers for which you want to trigger the webhook.
+6. Select **Save** to save your configurations.
+
+
diff --git a/docs/user-guide/creating-application/workflow/plugins/copy-container-image.md b/docs/user-guide/creating-application/workflow/plugins/copy-container-image.md
new file mode 100644
index 0000000000..0910c3b8fd
--- /dev/null
+++ b/docs/user-guide/creating-application/workflow/plugins/copy-container-image.md
@@ -0,0 +1,73 @@
+# Copy Container Image
+
+## Introduction
+
+Building container images in CI often results in a growing number of images, not all of which are production-ready. Therefore, it's a best practice to maintain a separate repository exclusively for storing production-builds. However, this would involve copying the container image (production-ready) from your existing repository to the production repository.
+
+This plugin helps you copy a container image to a desired container [repository](../../../../reference/glossary.md#repo). The pushing of image can be between repositories of the same container [registry](../../../../reference/glossary.md#containeroci-registry) or between repositories of different container registry. One of the major usecases this plugin serves is multi-cloud deployments.
+
+The plugin can be used at post CI, pre-CD, and post-CD. Moreover, you can also [customize the image tag pattern](../cd-pipeline.md#custom-image-tag-pattern) for the copied image.
+
+## Steps to Use
+
+1. Go to **App Configuration** tab of your application.
+
+2. Select **Workflow Editor** and click your deployment pipeline.
+
+ 
+
+3. In this example, we will be adding the plugin in pre-CD stage; therefore, go to **Pre-Deployment stage** tab of your deployment pipeline and click **Add task**.
+
+ 
+
+4. From the list of plugins, choose **Copy container image**.
+
+ 
+
+5. Add the image destination in the field given for **DESTINATION_INFO** variable. The format is `registry-name | username/repository-name`.
+
+ 
+
+ * **registry-name** is the name you gave to your container registry while adding it in [Global Configuration → OCI/Container Registry](../../../global-configurations/container-registries.md#add-container-registry).
+
+ * **user-name** is the your account name registered with you container registry, e.g., DockerHub.
+
+ * **repository-name** is the name of the repository within your container registry that hosts the container images of your application.
+
+6. Click **Update Pipeline**.
+
+7. Go to the **Build & Deploy** tab of your application and click **Select Image** in the pre-deployment stage.
+
+ 
+
+8. Choose a CI image that you wish to copy to the destination and click **Trigger Stage**.
+
+ 
+
+9. The copying process will initiate, and once it is successful, the [tag for the copied image](../cd-pipeline.md#custom-image-tag-pattern) would reflect at all relevant screens:
+
+ * **Destination Repository**
+
+ 
+
+ * **CD Pipeline (Image Selection)**
+
+ 
+
+ 
+
+{% hint style="info" %}
+You can also filter out specific images (of target repository) from deployment. Refer [Filter Condition](../../../global-configurations/filter-condition.md) to know the process.
+{% endhint %}
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/user-guide/deploying-application/triggering-cd.md b/docs/user-guide/deploying-application/triggering-cd.md
index 3d2c0a46fc..3af8bcbd6d 100644
--- a/docs/user-guide/deploying-application/triggering-cd.md
+++ b/docs/user-guide/deploying-application/triggering-cd.md
@@ -1,70 +1,107 @@
# Triggering CD Pipelines
-After CI pipeline is complete, CD pipeline can be triggered by clicking `Select Image`.
+After the [CI pipeline](./triggering-ci.md) is complete, you can trigger the CD pipeline.
-
+1. Go to the `Build & Deploy` tab of your application and click **Select Image** in the CD pipeline.
-Select an image to deploy and then click `Deploy` to trigger the CD pipeline.
+ 
-
+2. Select an image to deploy and then click **Deploy** to trigger the CD pipeline.
-The currently deployed images are tagged as `Active on `.
+ 
+
+However, if an image is already deployed, you can identify it by the tag `Active on `.
+
+
## Manual Approval for Deployment
-When manual approval is enabled for the deployment pipeline, you are required to request image approval before each deployment. Alternatively, you can only deploy images that have already been approved once.
+When [manual approval is enabled](../creating-application/workflow/cd-pipeline.md#4-manual-approval-for-deployment) for the deployment pipeline configured in the workflow, you are expected to request for an image approval before each deployment. Alternatively, you can deploy images that have already been approved once.
+
+If no approved images are available or the current image is already deployed, you won't see any images for deployment when clicking **Select Image**.
+
+
+
+### Requesting for Image Approval
+
+Users need to have [Build & deploy permission](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to request for an image approval.
+
+To request an image approval, follow these steps:
+
+1. Navigate to the `Build & Deploy` page, and click the **Approval for deployment** icon.
+
+ 
+
+2. Click the **Request Approval** button present on the image for which you want to request an approval and click **Submit Request**.
+
+ 
+
+ In case you have configured [SES or SMTP on Devtron](../global-configurations/manage-notification.md#notification-configurations), you can directly choose the approver(s) from the list of approvers as shown below.
+
+ 
+
+ The users you selected will receive an approval request via email. Any user with 'Image approver' permission alongwith access to the given application and given environment would be able to approve the image.
+
+
+#### Extras
+
+* In case you wish to cancel the image approval request, you can do so from the `Approval pending` tab as shown in the below image.
+
+ 
+
+* If you've received an approval but no longer want the image to be deployable, you can let the approval expire.
-When no approved image is available or if the image is already deployed, you will not see any image available for deployment upon clicking the `Select Image` button.
+ 
-
+### Accepting Image Approval Request
-### Request For Image Approval
+By default, super-admin users are considered as the default approvers. Users who build the image and/or request for its approval, cannot self-approve it even if they have super-admin privileges.
-To request for image approval, please follow these steps:
+Users with `Approver` permission (for the specific application and environment) can also approve a deployment. This permission can be granted to users from [`User Permissions`](../global-configurations/authorization/user-access.md#role-based-access-levels) present in [Global Configurations](../global-configurations/README.md).
-1. Navigate to `Build & Deploy` page, and click on the `Approval for deployment` button.
+In case [SES](../global-configurations/manage-notification.md#manage-ses-configurations) or [SMTP](../global-configurations/manage-notification.md#manage-smtp-configurations) was configured in Devtron, and the user chose the approvers while raising an image approval request, the approvers would receive an email notification as shown below:
-
+
-2. Click on `Request Approval` button present on the image for which you want to request approval and the click on `Submit Request`.
+To approve an image approval request, follow these steps:
-
+1. Go to the `Build & Deploy` page and click the `Approval for deployment` button.
-**NOTE**: You have the option to cancel the approval request from the `Approval Pending` section.
+ 
-### Approve Image Approval Request
+2. Switch to the `Approval pending` tab. Here, you will get a list of images that are awaiting approval.
-To approve an image approval request, please follow these steps:
+ 
-1. Go to the `Build & Deploy` page and click the **Approval for deployment** button.
+3. Click **Approve** followed by **Approve Request** button.
-
+ 
-2. Switch to the `Approval Pending` tab. Here, you will find all the images that are awaiting approval.
+### Deploying Approved Image
-3. Click the **Approve** button, and then **Approve Request** to grant approval to the request.
+Users need to have [Build & deploy permission](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the respective environment and application) to select and deploy an approved image.
-
+In case the super-admin has set the minimum number of approval to more than 1 (in [workflow](../creating-application/workflow/cd-pipeline.md#4-manual-approval-for-deployment)), you must wait for all approvals before deploying the image. In other words, partially approved image will not be eligible for deployment.
-### Approvers for Deployment
+
-By default, super admin users are considered as the default approvers. However, any user can be granted approver permission from the user-access section.
+To deploy an approved image, follow these steps:
-All users with `Approver` permission for the specific application and environment are authorized to approve deployments.
+1. Navigate to the `Build & Deploy` tab and click **Select Image**.
-Please note that the user who built the image and/or requested approval cannot self-approve, even if they have super-admin privileges.
+ 
-`Approver` role can be provided to users via [`User Permissions`](../global-configurations/authorization/user-access.md#role-based-access-levels)
+2. You will find all the approved images listed under the `Approved images` section. From the list, you can select the desired image and deploy it to your environment.
-After the images have been approved, navigate to the `Build and Deploy` tab and click on `Select Image`. You will find all the approved images listed under the `Approved Images` section. From this section, you can select the desired approved image and deploy it to the environment.
+ 
-
+3. You can view the status of current deployment in the `App Details` tab.
-The status of the current deployment can be viewed by clicking **App Details** that will show the `Progressing`state for 1-2 minutes and then gradually shows `Healthy` state, based on the deployment strategy.
+ 
-
+The status initially appears as `Progressing` for approximately 1-2 minutes, and then gradually transitions to `Healthy` state based on the deployment strategy.
-Here, triggering CD pipeline is successful and the deployment is in "Healthy" state.
+Here, our CD pipeline trigger was successful and the deployment is in `Healthy` state.
-[To further diagnose deployments, Click here](../debugging-deployment-and-monitoring.md)
+To further diagnose the deployments, [click here](../debugging-deployment-and-monitoring.md)
diff --git a/docs/user-guide/global-configurations/pull-image-digest.md b/docs/user-guide/global-configurations/pull-image-digest.md
new file mode 100644
index 0000000000..7a07b723e1
--- /dev/null
+++ b/docs/user-guide/global-configurations/pull-image-digest.md
@@ -0,0 +1,54 @@
+# Pull Image Digest
+
+## Introduction
+
+Devtron offers the option to pull container images using digest. Refer [CD Pipeline - Image Digest](../creating-application/workflow/cd-pipeline.md#pull-container-image-with-image-digest) to know the purpose it serves.
+
+Though it can be enabled by an application-admin for a given CD Pipeline, Devtron also allows super-admins to enable pull image digest at environment level.
+
+This helps in better governance and less repetitiveness if you wish to manage pull image digest for multiple applications across environments.
+
+{% hint style="warning" %}
+### Who Can Perform This Action?
+Users need to have super-admin permission to enable pull image digest at environment level.
+{% endhint %}
+
+---
+
+## Steps to Enable Pull Image Digest
+
+From the left sidebar, go to **Global Configurations** → **Pull Image Digest**.
+
+As a super-admin, you can decide whether you wish to enable pull image digest [for all environments](#for-all-environments) or [for specific environments](#for-specific-environments).
+
+### For all Environments
+
+This is for enabling pull image digest for deployment to all environments.
+
+1. Enable the toggle button next to `Pull image digest for all existing & future environments`.
+
+ 
+
+2. Click **Save Changes**.
+
+ 
+
+
+### For Specific Environments
+
+This is for enabling pull image digest for specific environments. Therefore, only those applications deploying to selected environment(s) will have pull image digest enabled in its CD pipeline.
+
+1. Use the checkbox to choose one or more environments present within the list of clusters you have on Devtron.
+
+ 
+
+2. Click **Save Changes**.
+
+Once you enable pull image digest for a given environment in Global Configurations, users won't be able to modify the [image digest setting in the CD pipeline](../creating-application/workflow/cd-pipeline.md#pull-container-image-with-image-digest). The toggle button would appear disabled for that environment as shown below.
+
+
+
+
+
+
+