From 39fe99ff5265bb7abeab86802dd67ea461791e7b Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Sun, 4 Jan 2026 15:04:48 +0530 Subject: [PATCH 1/6] ADD managingApp/triggering-a-deployment Signed-off-by: rahulshendre --- .../triggering-a-deployment.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md new file mode 100644 index 0000000000..7c86a458ee --- /dev/null +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -0,0 +1,49 @@ +--- +title: "Triggering a deployment" +linkTitle: "Triggering a deployment" +weight: 4 +description: > + This page describes when a deployment is triggered automatically and how to manually trigger a deployment. +--- + +PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or infrastructure, they will send a pull request to that Git repository to propose the change. The state defined in Git is the desired state for the application and infrastructure running in the cluster. + +PipeCD applies the proposed changes to running resources in the cluster by triggering needed deployments for applications. The deployment mission is syncing all running resources of the application in the cluster to the state specified in the newest commit in Git. + +By default, when a new merged pull request touches an application, a new deployment for that application will be triggered to execute the sync process. But users can configure the application to control when a new deployment should be triggered or not. For example, using [`onOutOfSync`](#trigger-configuration) to enable the ability to attempt to resolve `OUT_OF_SYNC` state whenever a configuration drift has been detected. + +### Trigger configuration + +Configuration for the trigger used to determine whether we trigger a new deployment. There are several configurable types: + +- `onCommit`: Controls triggering new deployment when new Git commits touched the application. +- `onCommand`: Controls triggering new deployment when received a new `SYNC` command. +- `onOutOfSync`: Controls triggering new deployment when application is at `OUT_OF_SYNC` state. +- `onChain`: Controls triggering new deployment when the application is counted as a node of some chains. + +See [Configuration Reference](../../configuration-reference/#deploymenttrigger) for the full configuration. + +After a new deployment is triggered, it will be queued to be handled by the appropriate `piped`. At this time, the deployment pipeline has not been decided yet. `piped` schedules all deployments of applications to ensure that for each application only one deployment will be executed at the same time. When no deployment of an application is running, `piped` picks a queued one to plan the deploying pipeline. `piped` plans the deploying pipeline based on the application configuration and the diff between the running state and the specified state in the newest commit. +For example: + +- when the merged pull request updated a Deployment's container image or updated a mounting ConfigMap or Secret, `piped` planner will decide that the deployment should use the specified pipeline to do a progressive deployment. +- when the merged pull request just updated the `replicas` number, `piped` planner will decide to use a quick sync to scale the resources. + +You can force `piped` planner to decide to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. + +After being planned, the deployment will be executed as the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page. + +![A screenshot of a running deployment on the Deployment Details Page](/images/deployment-details.png) +

+A Running Deployment at the Deployment Details Page +

+ +As explained above, by default all deployments will be triggered automatically by checking the merged commits but you also can manually trigger a new deployment from web UI. + +By clicking on `SYNC` button at the application details page, a new deployment for that application will be triggered to sync the application to be the state specified at the newest commit of the master branch (default branch). + +![Application Details Page](/images/application-details.png) +

+Application Details Page +

+ From 6f438c6a9d282356b752edf058c9a068db38b65c Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Mon, 5 Jan 2026 22:42:21 +0530 Subject: [PATCH 2/6] improving readability Signed-off-by: rahulshendre --- .../triggering-a-deployment.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md index 7c86a458ee..4e26f4fd03 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -6,24 +6,28 @@ description: > This page describes when a deployment is triggered automatically and how to manually trigger a deployment. --- -PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or infrastructure, they will send a pull request to that Git repository to propose the change. The state defined in Git is the desired state for the application and infrastructure running in the cluster. +PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or the infrastructure, they will have to open a pull request to the respective Git repository to propose the changes. The state defined in Git is the desired state for the application and infrastructure running in the cluster. -PipeCD applies the proposed changes to running resources in the cluster by triggering needed deployments for applications. The deployment mission is syncing all running resources of the application in the cluster to the state specified in the newest commit in Git. +PipeCD applies these changes by triggering deployments for affected applications. Each deployment synchronizes the running resources in the cluster to match the state defined in the latest Git commit. -By default, when a new merged pull request touches an application, a new deployment for that application will be triggered to execute the sync process. But users can configure the application to control when a new deployment should be triggered or not. For example, using [`onOutOfSync`](#trigger-configuration) to enable the ability to attempt to resolve `OUT_OF_SYNC` state whenever a configuration drift has been detected. +By default, PipeCD triggers a new deployment when you merge a pull request. +You can customize this behavior in your application configuration file (app.pipecd.yaml) to control whether and when deployments run. +For example, you can use [`onOutOfSync`](#trigger-configuration) to automatically trigger a deployment whenever PipeCD detects a configuration drift and the application enters an OUT_OF_SYNC state. ### Trigger configuration -Configuration for the trigger used to determine whether we trigger a new deployment. There are several configurable types: +You can configure when PipeCD triggers a new deployment. The following trigger types are available: -- `onCommit`: Controls triggering new deployment when new Git commits touched the application. -- `onCommand`: Controls triggering new deployment when received a new `SYNC` command. -- `onOutOfSync`: Controls triggering new deployment when application is at `OUT_OF_SYNC` state. -- `onChain`: Controls triggering new deployment when the application is counted as a node of some chains. +- `onCommit`: Triggers a deployment when new Git commits affect the application. +- `onCommand`: Triggers a deployment when the application receives a SYNC command. +- `onOutOfSync`: Triggers a deployment when the application enters an OUT_OF_SYNC state. +- `onChain`: Triggers a deployment when the application is part of a deployment chain. -See [Configuration Reference](../../configuration-reference/#deploymenttrigger) for the full configuration. +For the full list of options, see [Configuration Reference](../../configuration-reference/#deploymenttrigger). -After a new deployment is triggered, it will be queued to be handled by the appropriate `piped`. At this time, the deployment pipeline has not been decided yet. `piped` schedules all deployments of applications to ensure that for each application only one deployment will be executed at the same time. When no deployment of an application is running, `piped` picks a queued one to plan the deploying pipeline. `piped` plans the deploying pipeline based on the application configuration and the diff between the running state and the specified state in the newest commit. +After a deployment is triggered, it is added to a queue and handled by the appropriate `piped`. At this stage, the deployment pipeline is not yet decided. +`piped` ensures that only one deployment runs per application at a time. If no deployment is currently running, `piped` selects a queued deployment and plans its pipeline. +The deployment pipeline is created based on the application configuration and the differences between the current running state and the desired state defined in the latest commit. For example: - when the merged pull request updated a Deployment's container image or updated a mounting ConfigMap or Secret, `piped` planner will decide that the deployment should use the specified pipeline to do a progressive deployment. @@ -31,16 +35,16 @@ For example: You can force `piped` planner to decide to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. -After being planned, the deployment will be executed as the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page. +After the planning, the deployment will be executed as the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page. ![A screenshot of a running deployment on the Deployment Details Page](/images/deployment-details.png)

A Running Deployment at the Deployment Details Page

-As explained above, by default all deployments will be triggered automatically by checking the merged commits but you also can manually trigger a new deployment from web UI. +Although the deployments are triggered automatically by default, you can also manually trigger a deployment from the web UI. -By clicking on `SYNC` button at the application details page, a new deployment for that application will be triggered to sync the application to be the state specified at the newest commit of the master branch (default branch). +By clicking the `SYNC` button at the application details page, a new deployment will be triggered to sync the application to the latest state of the master branch (default branch). ![Application Details Page](/images/application-details.png)

From 1dfe474b6e7f477f6faba00d2763ae8724561939 Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Tue, 6 Jan 2026 16:23:46 +0530 Subject: [PATCH 3/6] apply review suggestions Signed-off-by: rahulshendre --- .../managing-application/triggering-a-deployment.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md index 4e26f4fd03..9f08cf5248 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -6,7 +6,7 @@ description: > This page describes when a deployment is triggered automatically and how to manually trigger a deployment. --- -PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or the infrastructure, they will have to open a pull request to the respective Git repository to propose the changes. The state defined in Git is the desired state for the application and infrastructure running in the cluster. +PipeCD uses Git as a single source of truth; all application resources are defined declaratively and immutably in Git. Whenever a developer wants to update the application or infrastructure, they will have to open a pull request to that Git repository to propose the change. The state defined in Git is the desired state for the application and infrastructure running in the cluster. PipeCD applies these changes by triggering deployments for affected applications. Each deployment synchronizes the running resources in the cluster to match the state defined in the latest Git commit. @@ -28,21 +28,22 @@ For the full list of options, see [Configuration Reference](../../configuration- After a deployment is triggered, it is added to a queue and handled by the appropriate `piped`. At this stage, the deployment pipeline is not yet decided. `piped` ensures that only one deployment runs per application at a time. If no deployment is currently running, `piped` selects a queued deployment and plans its pipeline. The deployment pipeline is created based on the application configuration and the differences between the current running state and the desired state defined in the latest commit. + For example: -- when the merged pull request updated a Deployment's container image or updated a mounting ConfigMap or Secret, `piped` planner will decide that the deployment should use the specified pipeline to do a progressive deployment. -- when the merged pull request just updated the `replicas` number, `piped` planner will decide to use a quick sync to scale the resources. +- If a merged pull request updates a Deployment's container image or updates a mounted ConfigMap or Secret, `piped` planner decides to use the specified pipeline for a progressive deployment. +- If a merged pull request only updates the `replicas` number, `piped` planner decides to use a quick sync to scale the resources. -You can force `piped` planner to decide to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. +You can configure `piped` planner to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. -After the planning, the deployment will be executed as the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page. +After the planning, the deployment will be executed as per the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page on the Web UI. ![A screenshot of a running deployment on the Deployment Details Page](/images/deployment-details.png)

A Running Deployment at the Deployment Details Page

-Although the deployments are triggered automatically by default, you can also manually trigger a deployment from the web UI. +Although the deployments are triggered automatically by default, you can also manually trigger a deployment from the Web UI. By clicking the `SYNC` button at the application details page, a new deployment will be triggered to sync the application to the latest state of the master branch (default branch). From f79a2c8bdc02e7d8597378449f4cf8713248e6c5 Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Wed, 7 Jan 2026 16:13:35 +0530 Subject: [PATCH 4/6] address review Signed-off-by: rahulshendre --- .../user-guide/managing-application/triggering-a-deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md index 9f08cf5248..2b6385a5d3 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -27,7 +27,7 @@ For the full list of options, see [Configuration Reference](../../configuration- After a deployment is triggered, it is added to a queue and handled by the appropriate `piped`. At this stage, the deployment pipeline is not yet decided. `piped` ensures that only one deployment runs per application at a time. If no deployment is currently running, `piped` selects a queued deployment and plans its pipeline. -The deployment pipeline is created based on the application configuration and the differences between the current running state and the desired state defined in the latest commit. +The deployment pipeline is created based on the application configuration and the differences between the current running state and the desired state defined in the latest commit. For example: From f8268f1365940317dea30f00209ea94a1eed77de Mon Sep 17 00:00:00 2001 From: Eeshaan Sawant <100678386+eeshaanSA@users.noreply.github.com> Date: Thu, 8 Jan 2026 14:38:40 +0530 Subject: [PATCH 5/6] Update docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md Signed-off-by: Eeshaan Sawant <100678386+eeshaanSA@users.noreply.github.com> --- .../user-guide/managing-application/triggering-a-deployment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md index 2b6385a5d3..169ddf5d8c 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -12,6 +12,7 @@ PipeCD applies these changes by triggering deployments for affected applications By default, PipeCD triggers a new deployment when you merge a pull request. You can customize this behavior in your application configuration file (app.pipecd.yaml) to control whether and when deployments run. + For example, you can use [`onOutOfSync`](#trigger-configuration) to automatically trigger a deployment whenever PipeCD detects a configuration drift and the application enters an OUT_OF_SYNC state. ### Trigger configuration From 8e9ffd20885533f7bab672cc0d73e698195dbc24 Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Thu, 8 Jan 2026 15:13:32 +0530 Subject: [PATCH 6/6] using piped only instead of piped planner Signed-off-by: rahulshendre --- .../managing-application/triggering-a-deployment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md index 169ddf5d8c..a9aff81943 100644 --- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md +++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/triggering-a-deployment.md @@ -32,10 +32,10 @@ The deployment pipeline is created based on the application configuration and th For example: -- If a merged pull request updates a Deployment's container image or updates a mounted ConfigMap or Secret, `piped` planner decides to use the specified pipeline for a progressive deployment. -- If a merged pull request only updates the `replicas` number, `piped` planner decides to use a quick sync to scale the resources. +- If a merged pull request updates a Deployment's container image or updates a mounted ConfigMap or Secret, `piped` decides to use the specified pipeline for a progressive deployment. +- If a merged pull request only updates the `replicas` number, `piped` decides to use a quick sync to scale the resources. -You can configure `piped` planner to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. +You can configure `piped` to use the [QuickSync](../../../concepts/#sync-strategy) or the specified pipeline based on the commit message by configuring [CommitMatcher](../../configuration-reference/#commitmatcher) in the application configuration. After the planning, the deployment will be executed as per the decided pipeline. The deployment execution including the state of each stage as well as their logs can be viewed in real time on the deployment details page on the Web UI.