From fd6ab645ab62c3da0c59ee5b8af34ab7f6d751bc Mon Sep 17 00:00:00 2001
From: Shivansh Sahu <sahushivansh142@gmail.com>
Date: Fri, 13 Mar 2026 06:23:04 +0000
Subject: [PATCH 1/4] docs(v1): add comprehensive configuration references for
 app and piped

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>
---
 .../configuration-reference.md                |  51 +++-
 .../managing-piped/configuration-reference.md | 261 ++++++------------
 2 files changed, 139 insertions(+), 173 deletions(-)

diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
index df449655b1..18bb15bf59 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
@@ -6,7 +6,50 @@ description: >
   Learn about all the configurable fields in the application configuration file.
 ---
 
->**Note:**
->PipeCD v1 documentation is still a work in progress. We are updating this configuration reference.
-> Until then, [see configurable fields for the application configuration file for v0.55](../../../docs-v0.55.x/user-guide/configuration-reference.md), and if you have any questions, [reach out to us](../../../../../../README.md#community-and-development) using one of our communication channels.
->Happy PipeCDing!
+This page describes all configurable fields in the application configuration for PipeCD v1.
+
+Unlike previous versions, PipeCD v1 unifies all application types under a single `Application` kind. The specific platform (Kubernetes, Terraform, Cloud Run, etc.) is now defined using a platform label.
+
+### Example `app.config`
+
+```yaml
+apiVersion: pipecd.dev/v1beta1
+kind: Application
+labels:
+  pipecd.dev/platform: KUBERNETES # Or TERRAFORM, CLOUDRUN, LAMBDA, ECS
+spec:
+  name: my-app
+  description: "My unified v1 application"
+  plugins: {}
+  pipeline: {}
+```
+
+## Application Configuration
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `apiVersion` | string | `pipecd.dev/v1beta1` | Yes |
+| `kind` | string | `Application` | Yes |
+| `labels` | map[string]string | Additional attributes to identify applications. Must include the `pipecd.dev/platform` label to specify the platform type. | Yes |
+| `spec.name` | string | The application name. | Yes |
+| `spec.description` | string | Notes on the Application. | No |
+| `spec.planner` | DeploymentPlanner | Configuration used while planning the deployment. | No |
+| `spec.commitMatcher` | DeploymentCommitMatcher | Forcibly use QuickSync or Pipeline when commit message matched the specified pattern. | No |
+| `spec.pipeline` | Pipeline | Pipeline definition for progressive delivery. | No |
+| `spec.trigger` | Trigger | Configuration used to determine if a new deployment should be triggered. | No |
+| `spec.postSync` | PostSync | Extra actions to execute once the deployment is triggered. | No |
+| `spec.timeout` | duration | The maximum length of time to execute deployment before giving up. Default is `6h`. | No |
+| `spec.encryption` | SecretEncryption | List of encrypted secrets and targets that should be decoded before using. | No |
+| `spec.attachment` | Attachment | List of files that should be attached to application manifests before using. | No |
+| `spec.notification` | DeploymentNotification | Additional configuration for sending notifications to external services. | No |
+| `spec.eventWatcher` | []EventWatcherConfig | List of the configurations for the event watcher. | No |
+| `spec.driftDetection` | [DriftDetection](#driftdetection) | Configuration for drift detection. | No |
+| `spec.plugins` | map[string]any | List of the configurations for plugins. This field is plugin-specific. | No |
+
+*(Note: The `spec.plugins` structures depend on the value of the `pipecd.dev/platform` label. See the specific Plugin documentation for deeper fields).*
+
+## DriftDetection
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `ignoreFields` | []string | List of `apiVersion:kind:namespace:name#fieldPath` to ignore in diffs. | No |
diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
index 0d5f94eb4d..5275aba157 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
@@ -6,204 +6,119 @@ description: >
   Learn about all the configurable fields in the `piped` configuration file.
 ---
 
->**Note:**
->PipeCD v1 documentation is still a work in progress. We are updating this configuration reference.
-> Until then, [see configurable fields for the piped configuration file for v0.55](../../../docs-v0.55.x/user-guide/managing-piped/configuration-reference.md), and if you have any questions, [reach out to us](../../../../../../README.md#community-and-development) using one of our communication channels.
->Happy PipeCDing!
+This page describes all configurable fields for the Piped (`piped.config`) configuration file in PipeCD v1.
 
-<!-- ``` yaml
+In v1, the architecture has shifted to a plugin-based model. The old `platformProviders` have been replaced by `plugins` (which specify the tool binaries to load) and `deployTargets` (where to deploy, nested under plugins). `chartRepositories` and `analysisProviders` have also been moved or removed from the top level.
+
+### Example `piped.config`
+
+```yaml
 apiVersion: pipecd.dev/v1beta1
 kind: Piped
 spec:
-  projectID: ...
-  pipedID: ...
-  ...
+  projectID: my-project
+  pipedID: my-piped-id
+  pipedKeyFile: /etc/piped-secret/piped-key
+  apiAddress: grpc.pipecd.dev:443
+  plugins:
+    - name: k8s_plugin
+      url: file:///path/to/k8s_plugin
+      port: 8081
+      deployTargets:
+        - name: dev-cluster
+          labels:
+            env: dev
+          config:
+            masterURL: http://cluster-dev
+            kubeConfigPath: ./kubeconfig-dev
 ```
 
 ## Piped Configuration
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| projectID | string | The identifier of the PipeCD project where this piped belongs to. | Yes |
-| pipedID | string | The generated ID for this piped. | Yes |
-| pipedKeyFile | string | The path to the file containing the generated key string for this piped. | Yes |
-| pipedKeyData | string | Base64 encoded string of Piped key. Either pipedKeyFile or pipedKeyData must be set. | Yes |
-| apiAddress | string | The address used to connect to the Control Plane's API in format `host:port`. | Yes |
-| syncInterval | duration | How often to check whether an application should be synced. Default is `1m`. | No |
-| appConfigSyncInterval | duration | How often to check whether application configuration files should be synced. Default is `1m`. | No |
-| git | [Git](#git) | Git configuration needed for Git commands. | No |
-| repositories | [][Repository](#gitrepository) | List of Git repositories this piped will handle. | No |
-| chartRepositories | [][ChartRepository](#chartrepository) | List of Helm chart repositories that should be added while starting up. | No |
-| chartRegistries | [][ChartRegistry](#chartregistry) | List of helm chart registries that should be logged in while starting up. | No |
-| platformProviders | [][PlatformProvider](#platformprovider) | List of platform providers can be used by this piped. | No |
-| analysisProviders | [][AnalysisProvider](#analysisprovider) | List of analysis providers can be used by this piped. | No |
-| eventWatcher | [EventWatcher](#eventwatcher) | Optional Event watcher settings. | No |
-| secretManagement | [SecretManagement](#secretmanagement) | The using secret management method. | No |
-| notifications | [Notifications](#notifications) | Sending notifications to Slack, Webhook... | No |
-| appSelector | map[string]string | List of labels to filter all applications this piped will handle. Currently, it is only be used to filter the applications suggested for adding from the control plane. | No |
-
-## Git
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| username | string | The username that will be configured for `git` user. Default is `piped`. | No |
-| email | string | The email that will be configured for `git` user. Default is `pipecd.dev@gmail.com`. | No |
-| sshConfigFilePath | string | Where to write ssh config file. Default is `$HOME/.ssh/config`. | No |
-| host | string | The host name. Default is `github.com`. | No |
-| hostName | string | The hostname or IP address of the remote git server. Default is the same value with Host. | No |
-| sshKeyFile | string | The path to the private ssh key file. This will be used to clone the source code of the specified git repositories. | No |
-| sshKeyData | string | Base64 encoded string of SSH key. | No |
-| password | string | The base64 encoded password for git used while cloning above Git repository. | No |
-
-## GitRepository
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| repoID | string | Unique identifier to the repository. This must be unique in the piped scope. | Yes |
-| remote | string | Remote address of the repository used to clone the source code. e.g. `git@github.com:org/repo.git` | Yes |
-| branch | string | The branch will be handled. | Yes |
-
-## ChartRepository
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| type | string | The repository type. Currently, HTTP and GIT are supported. Default is HTTP. | No |
-| name | string | The name of the Helm chart repository. Note that is not a Git repository but a [Helm chart repository](https://helm.sh/docs/topics/chart_repository/). | Yes if type is HTTP |
-| address | string | The address to the Helm chart repository. | Yes if type is HTTP |
-| username | string | Username used for the repository backed by HTTP basic authentication. | No |
-| password | string | Password used for the repository backed by HTTP basic authentication. | No |
-| insecure | bool | Whether to skip TLS certificate checks for the repository or not. | No |
-| gitRemote | string | Remote address of the Git repository used to clone Helm charts. | Yes if type is GIT |
-| sshKeyFile | string | The path to the private ssh key file used while cloning Helm charts from above Git repository. | No |
+| --- | --- | --- | --- |
+| `apiVersion` | string | `pipecd.dev/v1beta1` | Yes |
+| `kind` | string | `Piped` | Yes |
+| `spec.projectID` | string | The identifier of the PipeCD project where this piped belongs to. | Yes |
+| `spec.pipedID` | string | The generated ID for this piped. | Yes |
+| `spec.pipedKeyFile` | string | The path to the file containing the generated key string for this piped. | Yes* |
+| `spec.pipedKeyData` | string | Base64 encoded string of Piped key. Either `pipedKeyFile` or `pipedKeyData` must be set. | Yes* |
+| `spec.name` | string | The name of this piped. | No |
+| `spec.apiAddress` | string | The address used to connect to the Control Plane's API. | Yes |
+| `spec.webAddress` | string | The address to the Control Plane's Web interface. | No |
+| `spec.syncInterval` | duration | How often to check whether an application should be synced. Default is `1m`. | No |
+| `spec.appConfigSyncInterval` | duration | How often to check whether an application configuration file should be synced. Default is `1m`. | No |
+| `spec.git` | [PipedGit](#pipedgit) | Configuration for Git executable needed for Git commands. | No |
+| `spec.repositories` | [][PipedRepository](#pipedrepository) | List of Git repositories this Piped should watch. | No |
+| `spec.plugins` | [][PipedPlugin](#pipedplugin) | List of architectural plugins (e.g., `k8s_plugin`, `terraform_plugin`) the Piped will run. | Yes |
+| `spec.notifications` | [Notifications](#notifications) | Configurations for sending deployment notifications. | No |
+| `spec.secretManagement` | [SecretManagement](#secretmanagement) | Configuration for decrypting secrets in manifests. | No |
+| `spec.eventWatcher` | [PipedEventWatcher](#pipedeventwatcher) | Optional settings for event watcher. | No |
+| `spec.appSelector` | map[string]string | List of labels to filter all applications this piped will handle. | No |
 
-## ChartRegistry
+## PipedGit
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| type | string | The registry type. Currently, only OCI is supported. Default is OCI. | No |
-| address | string | The address to the registry. | Yes |
-| username | string | Username used for the registry authentication. | No |
-| password | string | Password used for the registry authentication. | No |
+| --- | --- | --- | --- |
+| `username` | string | The username that will be configured for `git` user. Default is `piped`. | No |
+| `email` | string | The email that will be configured for `git` user. Default is `pipecd.dev@gmail.com`. | No |
+| `sshConfigFilePath` | string | Where to write ssh config file. Default is `$HOME/.ssh/config`. | No |
+| `host` | string | The host name. Default is `github.com`. | No |
+| `hostName` | string | The hostname or IP address of the remote git server. Default is the same value with Host. | No |
+| `sshKeyFile` | string | The path to the private ssh key file. This will be used to clone the source code of the specified git repositories. | No |
+| `sshKeyData` | string | Base64 encoded string of SSH key. | No |
+| `password` | string | The base64 encoded password for git used while cloning above Git repository via HTTPS. | No |
 
-## PlatformProvider
+## PipedRepository
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| name | string | The name of the platform provider. | Yes |
-| type | string | The platform provider type. Must be one of the following values:<br>`KUBERNETES`, `TERRAFORM`, `ECS`, `CLOUDRUN`, `LAMBDA`. | Yes |
-| config | [PlatformProviderConfig](#platformproviderconfig) | Specific configuration for the specified type of platform provider. | No |
+| --- | --- | --- | --- |
+| `repoID` | string | Unique identifier to the repository. This must be unique in the piped scope. | Yes |
+| `remote` | string | Remote address of the repository used to clone the source code. e.g. `git@github.com:org/repo.git` | Yes |
+| `branch` | string | The branch will be handled. | Yes |
 
-## PlatformProviderConfig
-
-Must be one of the following structs:
+## PipedPlugin
 
-### PlatformProviderKubernetesConfig
+Defines the external plugin binaries that this Piped agent should load to handle specific platforms.
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| masterURL | string | The master URL of the kubernetes cluster. Empty means in-cluster. | No |
-| kubectlVersion | string | Version of kubectl which will be used to connect to your cluster. Empty means the version set on [piped config](../user-guide/managing-piped/configuration-reference/#platformproviderkubernetesconfig) or [default version](https://github.com/pipe-cd/pipecd/blob/master/tool/piped-base/install-kubectl.sh#L24) will be used. | No |
-| kubeConfigPath | string | The path to the kubeconfig file. Empty means in-cluster. | No |
-| appStateInformer | [KubernetesAppStateInformer](#kubernetesappstateinformer) | Configuration for application resource informer. | No |
-
-### PlatformProviderTerraformConfig
+| --- | --- | --- | --- |
+| `name` | string | The name of the plugin (e.g., `k8s_plugin`). | Yes |
+| `url` | string | Source to download the plugin binary (schemes: `file`, `https`, `oci`). | Yes |
+| `port` | int | The port which the plugin listens to. | Yes |
+| `config` | object | Configuration for the plugin. | No |
+| `deployTargets` | [][PipedDeployTarget](#pipeddeploytarget) | The destination environments/clusters where the Piped is allowed to deploy applications. | No |
 
-| Field | Type | Description | Required |
-|-|-|-|-|
-| vars | []string | List of variables that will be set directly on terraform commands with `-var` flag. The variable must be formatted by `key=value`. | No |
-| driftDetectionEnabled | bool | Enable drift detection. This is a temporary option and will be possibly removed in the future release. Default is `true` | No |
+## PipedDeployTarget
 
-### PlatformProviderCloudRunConfig
+Defines the target environments where applications can be deployed.
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| project | string | The GCP project hosting the Cloud Run service. | Yes |
-| region | string | The region of running Cloud Run service. | Yes |
-| credentialsFile | string | The path to the service account file for accessing Cloud Run service. | No |
+| --- | --- | --- | --- |
+| `name` | string | The unique name of the deploy target. | Yes |
+| `labels` | map[string]string | Attributes to identify the target (e.g., `env: production`). | No |
+| `config` | object | The platform-specific connection configuration. | Yes |
 
-### PlatformProviderLambdaConfig
+## PipedEventWatcher
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| region | string | The region of running Lambda service. | Yes |
-| credentialsFile | string | The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format [~/.aws/credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). | No |
-| roleARN | string | The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService. | No |
-| tokenFile | string | The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService. | No |
-| profile | string | The profile to use for logging into AWS cluster. The default value is `default`. | No |
-| awsAPIPollingInterval | duration | The interval of periodical calls of AWS APIs. Currently, this is an interval of refreshing the live state of Lambda functions. Default is 15s. | No |
+| --- | --- | --- | --- |
+| `checkInterval` | duration | Interval to fetch the latest event and compare it. | No |
+| `gitRepos` | [][PipedEventWatcherGitRepo](#pipedeventwatchergitrepo) | The configuration list of git repositories to be observed. | No |
 
-### PlatformProviderECSConfig
+## PipedEventWatcherGitRepo
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| region | string | The region of running ECS cluster. | Yes |
-| credentialsFile | string | The path to the credential file for logging into AWS cluster. If this value is not provided, piped will read credential info from environment variables. It expects the format [~/.aws/credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) | No |
-| roleARN | string | The IAM role arn to use when assuming an role. Required if you want to use the AWS SecurityTokenService. | No |
-| tokenFile | string | The path to the WebIdentity token the SDK should use to assume a role with. Required if you want to use the AWS SecurityTokenService. | No |
-| profile | string | The profile to use for logging into AWS cluster. The default value is `default`. | No |
-
-## KubernetesAppStateInformer
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| namespace | string | Only watches the specified namespace. Empty means watching all namespaces. | No |
-| includeResources | [][KubernetesResourcematcher](#kubernetesresourcematcher) | List of resources that should be added to the watching targets. | No |
-| excludeResources | [][KubernetesResourcematcher](#kubernetesresourcematcher) | List of resources that should be ignored from the watching targets. | No |
-
-### KubernetesResourceMatcher
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| apiVersion | string | The APIVersion of the kubernetes resource. | Yes |
-| kind | string | The kind name of the kubernetes resource. Empty means all kinds are matching. | No |
-
-## AnalysisProvider
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| name | string | The unique name of the analysis provider. | Yes |
-| type | string | The provider type. Currently, only PROMETHEUS, DATADOG are available. | Yes |
-| config | [AnalysisProviderConfig](#analysisproviderconfig) | Specific configuration for the specified type of analysis provider. | Yes |
-
-## AnalysisProviderConfig
-
-Must be one of the following structs:
-
-### AnalysisProviderPrometheusConfig
-| Field | Type | Description | Required |
-|-|-|-|-|
-| address | string | The Prometheus server address. | Yes |
-| usernameFile | string | The path to the username file. | No |
-| passwordFile | string | The path to the password file. | No |
-
-### AnalysisProviderDatadogConfig
-| Field | Type | Description | Required |
-|-|-|-|-|
-| address | string | The address of Datadog API server. Only "datadoghq.com", "us3.datadoghq.com", "datadoghq.eu", "ddog-gov.com" are available. Defaults to "datadoghq.com" | No |
-| apiKeyFile | string | The path to the api key file. | Yes |
-| applicationKeyFile | string | The path to the application key file. | Yes |
-| apiKeyData | string | Base64 API Key for Datadog API server. Either apiKeyData or apiKeyFile must be set | No |
-| applicationKeyData | string | Base64 Application Key for Datadog API server. Either applicationKeyFile or applicationKeyData must be set | No |
-
-## EventWatcher
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| checkInterval | duration | Interval to fetch the latest event and compare it with one defined in EventWatcher config files. Defaults to `1m`. | No |
-| gitRepos | [][EventWatcherGitRepo](#eventwatchergitrepo) | The configuration list of git repositories to be observed. Only the repositories in this list will be observed by Piped. | No |
-
-### EventWatcherGitRepo
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| repoId | string | Id of the git repository. This must be unique within the repos' elements. | Yes |
-| commitMessage | string | The commit message used to push after replacing values. Default message is used if not given. | No |
-| includes | []string | The paths to EventWatcher files to be included. Patterns can be used like `foo/*.yaml`. | No |
-| excludes | []string | The paths to EventWatcher files to be excluded. Patterns can be used like `foo/*.yaml`. This is prioritized if both includes and this are given. | No |
+| --- | --- | --- | --- |
+| `repoId` | string | Id of the git repository. Must be unique. | Yes |
+| `commitMessage` | string | The commit message used to push after replacing values. | No |
+| `includes` | []string | The paths to EventWatcher files to be included. e.g. `foo/*.yaml`. | No |
+| `excludes` | []string | The paths to EventWatcher files to be excluded. Prioritized over `includes`. | No |
 
 ## SecretManagement
 
 | Field | Type | Description | Required |
+<<<<<<< HEAD
 |-|-|-|-|
 | type | string | Which management method should be used. Default is `KEY_PAIR`. | Yes |
 | config | [SecretManagementConfig](#secretmanagementconfig) | Configuration for using secret management method. | Yes |
@@ -224,16 +139,22 @@ Must be one of the following structs:
 ### SecretManagementGCPKMS
 
 > WIP
+=======
+| --- | --- | --- | --- |
+| `type` | string | Which management service should be used (`KEY_PAIR`, `GCP_KMS`). | Yes |
+| `config` | object | Configuration for the specified secret management type. | Yes |
+>>>>>>> f9f7a119c (docs(v1): add comprehensive configuration references for app and piped)
 
 ## Notifications
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| routes | [][NotificationRoute](#notificationroute) | List of notification routes. | No |
-| receivers | [][NotificationReceiver](#notificationreceiver) | List of notification receivers. | No |
+| --- | --- | --- | --- |
+| `routes` | []NotificationRoute | List of notification routes. | No |
+| `receivers` | []NotificationReceiver | List of notification receivers. | No |
 
-### NotificationRoute
+*(See the source or previous docs for full Notifications routing references).*
 
+<<<<<<< HEAD
 | Field | Type | Description | Required |
 |-|-|-|-|
 | name | string | The name of the route. | Yes |
@@ -276,3 +197,5 @@ Must be one of the following structs:
 | signatureKey | string | The HTTP header key used to store the configured signature in each event. Default is "PipeCD-Signature". | No |
 | signatureValue | string | The value of signature included in header of each event request. It can be used to verify the received events. | No |
 | signatureValueFile | string | The path to the signature value file. | No | -->
+=======
+>>>>>>> f9f7a119c (docs(v1): add comprehensive configuration references for app and piped)

From 6e771f2a4470f1730bd420b593daec10067b104e Mon Sep 17 00:00:00 2001
From: Shivansh Sahu <sahushivansh142@gmail.com>
Date: Wed, 25 Mar 2026 19:15:45 +0000
Subject: [PATCH 2/4] docs(v1): add comprehensive config tables for app and
 piped configs per review

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>
---
 .../configuration-reference.md                | 27 +++++++++++++++++++
 .../managing-piped/configuration-reference.md | 21 ++++++++++++++-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
index 18bb15bf59..9f15fe8e1b 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
@@ -53,3 +53,30 @@ spec:
 | Field | Type | Description | Required |
 | --- | --- | --- | --- |
 | `ignoreFields` | []string | List of `apiVersion:kind:namespace:name#fieldPath` to ignore in diffs. | No |
+
+## Planner
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `alwaysUsePipeline` | bool | Whether to always use the pipeline for deployment instead of a QuickSync. | No |
+| `autoRollback` | bool | Whether to automatically rollback to the previous state when the deployment fails. | No |
+
+## Pipeline
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `stages` | []PipelineStage | List of stages to be executed sequentially during the deployment pipeline. | Yes |
+
+## Trigger
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `onCommit` | OnCommit | Configuration for triggering deployments upon new commits. | No |
+| `onCommand` | OnCommand | Configuration for triggering deployments via manual command. | No |
+| `onOutOfSync` | OnOutOfSync | Configuration for triggering deployments when drift is detected. | No |
+
+## PostSync
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `chain` | []PostSyncPlugin | List of plugins or tasks to execute after a successful synchronization. | Yes |
diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
index 5275aba157..87ceecd841 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
@@ -152,7 +152,26 @@ Must be one of the following structs:
 | `routes` | []NotificationRoute | List of notification routes. | No |
 | `receivers` | []NotificationReceiver | List of notification receivers. | No |
 
-*(See the source or previous docs for full Notifications routing references).*
+### NotificationRoute
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `name` | string | The name of the route. | Yes |
+| `receiver` | string | The name of receiver who will receive all matched events. | Yes |
+| `events` | []string | List of events that should be routed to the receiver. | No |
+| `ignoreEvents` | []string | List of events that should be ignored. | No |
+| `apps` | []string | List of applications where their events should be routed. | No |
+| `ignoreApps` | []string | List of applications where their events should be ignored. | No |
+| `labels` | map[string]string | List of labels where their events should be routed. | No |
+| `ignoreLabels` | map[string]string | List of labels where their events should be ignored. | No |
+
+### NotificationReceiver
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `name` | string | The name of the receiver. | Yes |
+| `slack` | NotificationReceiverSlack | Configuration for slack receiver. | No |
+| `webhook` | NotificationReceiverWebhook | Configuration for webhook receiver. | No |
 
 <<<<<<< HEAD
 | Field | Type | Description | Required |

From f8455cef292c43580e4fdcca854dfc39c63d7e28 Mon Sep 17 00:00:00 2001
From: Shivansh Sahu <sahushivansh142@gmail.com>
Date: Fri, 3 Apr 2026 18:06:02 +0000
Subject: [PATCH 3/4] docs(v1): add slack and webhook receiver config tables
 per review nit

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>
---
 .../managing-piped/configuration-reference.md | 103 ++++++++----------
 1 file changed, 45 insertions(+), 58 deletions(-)

diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
index 87ceecd841..4c10d02436 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-piped/configuration-reference.md
@@ -6,11 +6,11 @@ description: >
   Learn about all the configurable fields in the `piped` configuration file.
 ---
 
-This page describes all configurable fields for the Piped (`piped.config`) configuration file in PipeCD v1.
+This page describes all configurable fields for the piped (`piped.config`) configuration file in PipeCD v1.
 
-In v1, the architecture has shifted to a plugin-based model. The old `platformProviders` have been replaced by `plugins` (which specify the tool binaries to load) and `deployTargets` (where to deploy, nested under plugins). `chartRepositories` and `analysisProviders` have also been moved or removed from the top level.
+In v1, the architecture has shifted to a plugin-based model. The old `platformProviders` have been replaced by `plugins` (which specify the tool binaries to load) and `deployTargets` (where to deploy, nested under plugins). `analysisProviders` have been moved or removed from the top level. Additionally, `chartRepositories` and `chartRegistries` have been moved from the top level and are now configured individually under `spec.plugins[].config` for the relevant platform plugins (e.g., the Kubernetes plugin).
 
-### Example `piped.config`
+## Example `piped.config`
 
 ```yaml
 apiVersion: pipecd.dev/v1beta1
@@ -54,6 +54,7 @@ spec:
 | `spec.notifications` | [Notifications](#notifications) | Configurations for sending deployment notifications. | No |
 | `spec.secretManagement` | [SecretManagement](#secretmanagement) | Configuration for decrypting secrets in manifests. | No |
 | `spec.eventWatcher` | [PipedEventWatcher](#pipedeventwatcher) | Optional settings for event watcher. | No |
+| `spec.planPreview` | [PipedPlanPreview](#pipedplanpreview) | Optional settings for plan-preview feature. | No |
 | `spec.appSelector` | map[string]string | List of labels to filter all applications this piped will handle. | No |
 
 ## PipedGit
@@ -73,7 +74,7 @@ spec:
 
 | Field | Type | Description | Required |
 | --- | --- | --- | --- |
-| `repoID` | string | Unique identifier to the repository. This must be unique in the piped scope. | Yes |
+| `repoId` | string | Unique identifier to the repository. This must be unique in the piped scope. | Yes |
 | `remote` | string | Remote address of the repository used to clone the source code. e.g. `git@github.com:org/repo.git` | Yes |
 | `branch` | string | The branch will be handled. | Yes |
 
@@ -85,7 +86,7 @@ Defines the external plugin binaries that this Piped agent should load to handle
 | --- | --- | --- | --- |
 | `name` | string | The name of the plugin (e.g., `k8s_plugin`). | Yes |
 | `url` | string | Source to download the plugin binary (schemes: `file`, `https`, `oci`). | Yes |
-| `port` | int | The port which the plugin listens to. | Yes |
+| `port` | int | The port which the plugin listens to. | No |
 | `config` | object | Configuration for the plugin. | No |
 | `deployTargets` | [][PipedDeployTarget](#pipeddeploytarget) | The destination environments/clusters where the Piped is allowed to deploy applications. | No |
 
@@ -115,35 +116,42 @@ Defines the target environments where applications can be deployed.
 | `includes` | []string | The paths to EventWatcher files to be included. e.g. `foo/*.yaml`. | No |
 | `excludes` | []string | The paths to EventWatcher files to be excluded. Prioritized over `includes`. | No |
 
+## PipedPlanPreview
+
+| Field | Type | Description | Required |
+| --- | --- | --- | --- |
+| `workerNum` | int | Number of worker goroutines processing plan-preview commands. | No |
+| `commandQueueBufferSize` | int | Buffer size of the internal command channel. | No |
+| `commandCheckInterval` | duration | How often to poll for new plan-preview commands. | No |
+| `commandHandleTimeout` | duration | Default timeout for building each plan-preview result when the command does not specify one. | No |
+
 ## SecretManagement
 
 | Field | Type | Description | Required |
-<<<<<<< HEAD
-|-|-|-|-|
-| type | string | Which management method should be used. Default is `KEY_PAIR`. | Yes |
-| config | [SecretManagementConfig](#secretmanagementconfig) | Configuration for using secret management method. | Yes |
+| --- | --- | --- | --- |
+| `type` | string | Which management service should be used (`KEY_PAIR`, `GCP_KMS`). | Yes |
+| `config` | object | Configuration for the specified secret management type. | Yes |
 
 ## SecretManagementConfig
 
-Must be one of the following structs:
+Must be one of the following structs based on the `type` field:
 
 ### SecretManagementKeyPair
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| privateKeyFile | string | Path to the private RSA key file. | Yes |
-| privateKeyData | string | Base64 encoded string of private RSA key. Either privateKeyFile or privateKeyData must be set. | No |
-| publicKeyFile | string | Path to the public RSA key file. | Yes |
-| publicKeyData | string | Base64 encoded string of public RSA key. Either publicKeyFile or publicKeyData must be set. | No |
+| --- | --- | --- | --- |
+| `privateKeyFile` | string | Path to the private RSA key file. | Yes |
+| `privateKeyData` | string | Base64 encoded string of private RSA key. Either `privateKeyFile` or `privateKeyData` must be set. | No |
+| `publicKeyFile` | string | Path to the public RSA key file. | Yes |
+| `publicKeyData` | string | Base64 encoded string of public RSA key. Either `publicKeyFile` or `publicKeyData` must be set. | No |
 
 ### SecretManagementGCPKMS
 
-> WIP
-=======
+| Field | Type | Description | Required |
 | --- | --- | --- | --- |
-| `type` | string | Which management service should be used (`KEY_PAIR`, `GCP_KMS`). | Yes |
-| `config` | object | Configuration for the specified secret management type. | Yes |
->>>>>>> f9f7a119c (docs(v1): add comprehensive configuration references for app and piped)
+| `keyName` | string | The key name used for decrypting the sealed secret. | Yes |
+| `decryptServiceAccountFile` | string | The path to the service account used to decrypt secret. | Yes |
+| `encryptServiceAccountFile` | string | The path to the service account used to encrypt secret. | Yes |
 
 ## Notifications
 
@@ -160,6 +168,8 @@ Must be one of the following structs:
 | `receiver` | string | The name of receiver who will receive all matched events. | Yes |
 | `events` | []string | List of events that should be routed to the receiver. | No |
 | `ignoreEvents` | []string | List of events that should be ignored. | No |
+| `groups` | []string | List of event groups that should be routed to the receiver. | No |
+| `ignoreGroups` | []string | List of event groups that should be ignored. | No |
 | `apps` | []string | List of applications where their events should be routed. | No |
 | `ignoreApps` | []string | List of applications where their events should be ignored. | No |
 | `labels` | map[string]string | List of labels where their events should be routed. | No |
@@ -173,48 +183,25 @@ Must be one of the following structs:
 | `slack` | NotificationReceiverSlack | Configuration for slack receiver. | No |
 | `webhook` | NotificationReceiverWebhook | Configuration for webhook receiver. | No |
 
-<<<<<<< HEAD
-| Field | Type | Description | Required |
-|-|-|-|-|
-| name | string | The name of the route. | Yes |
-| receiver | string | The name of receiver who will receive all matched events. | Yes |
-| events | []string | List of events that should be routed to the receiver. | No |
-| ignoreEvents | []string | List of events that should be ignored. | No |
-| groups | []string | List of event groups should be routed to the receiver. | No |
-| ignoreGroups | []string | List of event groups should be ignored. | No |
-| apps | []string | List of applications where their events should be routed to the receiver. | No |
-| ignoreApps | []string | List of applications where their events should be ignored. | No |
-| labels | map[string]string | List of labels where their events should be routed to the receiver. | No |
-| ignoreLabels | map[string]string | List of labels where their events should be ignored. | No |
-
-
-### NotificationReceiver
-
-| Field | Type | Description | Required |
-|-|-|-|-|
-| name | string | The name of the receiver. | Yes |
-| slack | [NotificationReceiverSlack](#notificationreceiverslack) | Configuration for slack receiver. | No |
-| webhook | [NotificationReceiverWebhook](#notificationreceiverwebhook) | Configuration for webhook receiver. | No |
-
 #### NotificationReceiverSlack
 
+Use either `hookURL` alone, or `channelID` with an OAuth token (`oauthToken`, `oauthTokenData`, or `oauthTokenFile`). Do not set both.
+
 | Field | Type | Description | Required |
-|-|-|-|-|
-| hookURL | string | The hookURL of a slack channel. | Yes |
-| oauthToken | string | [The token for Slack API use.](https://api.slack.com/authentication/basics) (deprecated)| No |
-| oauthTokenData | string | Base64 encoded string of [The token for Slack API use.](https://api.slack.com/authentication/basics) | No |
-| oauthTokenFile | string | The path to the oauthToken file | No |
-| channelID | string | The channel id which slack api send to. | No |
-| mentionedAccounts | []string | The accounts to which slack api refers. This field supports both `@username` and `username` writing styles.| No |
-| mentionedGroups | []string | The groups to which slack api refers. This field supports both `<!subteam^groupname>` and `groupname` writing styles.| No |
+| --- | --- | --- | --- |
+| `hookURL` | string | The hook URL of a Slack channel. Required when not using OAuth token. | Yes* |
+| `oauthToken` | string | [The token for Slack API use.](https://api.slack.com/authentication/basics) (deprecated) | No |
+| `oauthTokenData` | string | Base64 encoded string of [the token for Slack API use.](https://api.slack.com/authentication/basics) | No |
+| `oauthTokenFile` | string | The path to the OAuth token file. | No |
+| `channelID` | string | The channel ID which the Slack API sends to. Required when using OAuth token. | Yes* |
+| `mentionedAccounts` | []string | The accounts to which slack api refers. This field supports both `@username` and `username` writing styles. | No |
+| `mentionedGroups` | []string | The groups to which slack api refers. This field supports both `<!subteam^groupname>` and `groupname` writing styles. | No |
 
 #### NotificationReceiverWebhook
 
 | Field | Type | Description | Required |
-|-|-|-|-|
-| url | string | The URL where notification event will be sent to. | Yes |
-| signatureKey | string | The HTTP header key used to store the configured signature in each event. Default is "PipeCD-Signature". | No |
-| signatureValue | string | The value of signature included in header of each event request. It can be used to verify the received events. | No |
-| signatureValueFile | string | The path to the signature value file. | No | -->
-=======
->>>>>>> f9f7a119c (docs(v1): add comprehensive configuration references for app and piped)
+| --- | --- | --- | --- |
+| `url` | string | The URL where notification event will be sent to. | Yes |
+| `signatureKey` | string | The HTTP header key used to store the configured signature in each event. Default is "PipeCD-Signature". | No |
+| `signatureValue` | string | The value of signature included in header of each event request. It can be used to verify the received events. | No |
+| `signatureValueFile` | string | The path to the signature value file. | No |

From be948884140c1473351f6be9c96b8daf744b2f46 Mon Sep 17 00:00:00 2001
From: Shivansh Sahu <sahushivansh142@gmail.com>
Date: Sat, 4 Apr 2026 17:03:13 +0000
Subject: [PATCH 4/4] chore: isolate piped config changes

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>
---
 .../configuration-reference.md                | 78 +------------------
 1 file changed, 4 insertions(+), 74 deletions(-)

diff --git a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
index 9f15fe8e1b..df449655b1 100644
--- a/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
+++ b/docs/content/en/docs-v1.0.x/user-guide/managing-application/configuration-reference.md
@@ -6,77 +6,7 @@ description: >
   Learn about all the configurable fields in the application configuration file.
 ---
 
-This page describes all configurable fields in the application configuration for PipeCD v1.
-
-Unlike previous versions, PipeCD v1 unifies all application types under a single `Application` kind. The specific platform (Kubernetes, Terraform, Cloud Run, etc.) is now defined using a platform label.
-
-### Example `app.config`
-
-```yaml
-apiVersion: pipecd.dev/v1beta1
-kind: Application
-labels:
-  pipecd.dev/platform: KUBERNETES # Or TERRAFORM, CLOUDRUN, LAMBDA, ECS
-spec:
-  name: my-app
-  description: "My unified v1 application"
-  plugins: {}
-  pipeline: {}
-```
-
-## Application Configuration
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `apiVersion` | string | `pipecd.dev/v1beta1` | Yes |
-| `kind` | string | `Application` | Yes |
-| `labels` | map[string]string | Additional attributes to identify applications. Must include the `pipecd.dev/platform` label to specify the platform type. | Yes |
-| `spec.name` | string | The application name. | Yes |
-| `spec.description` | string | Notes on the Application. | No |
-| `spec.planner` | DeploymentPlanner | Configuration used while planning the deployment. | No |
-| `spec.commitMatcher` | DeploymentCommitMatcher | Forcibly use QuickSync or Pipeline when commit message matched the specified pattern. | No |
-| `spec.pipeline` | Pipeline | Pipeline definition for progressive delivery. | No |
-| `spec.trigger` | Trigger | Configuration used to determine if a new deployment should be triggered. | No |
-| `spec.postSync` | PostSync | Extra actions to execute once the deployment is triggered. | No |
-| `spec.timeout` | duration | The maximum length of time to execute deployment before giving up. Default is `6h`. | No |
-| `spec.encryption` | SecretEncryption | List of encrypted secrets and targets that should be decoded before using. | No |
-| `spec.attachment` | Attachment | List of files that should be attached to application manifests before using. | No |
-| `spec.notification` | DeploymentNotification | Additional configuration for sending notifications to external services. | No |
-| `spec.eventWatcher` | []EventWatcherConfig | List of the configurations for the event watcher. | No |
-| `spec.driftDetection` | [DriftDetection](#driftdetection) | Configuration for drift detection. | No |
-| `spec.plugins` | map[string]any | List of the configurations for plugins. This field is plugin-specific. | No |
-
-*(Note: The `spec.plugins` structures depend on the value of the `pipecd.dev/platform` label. See the specific Plugin documentation for deeper fields).*
-
-## DriftDetection
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `ignoreFields` | []string | List of `apiVersion:kind:namespace:name#fieldPath` to ignore in diffs. | No |
-
-## Planner
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `alwaysUsePipeline` | bool | Whether to always use the pipeline for deployment instead of a QuickSync. | No |
-| `autoRollback` | bool | Whether to automatically rollback to the previous state when the deployment fails. | No |
-
-## Pipeline
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `stages` | []PipelineStage | List of stages to be executed sequentially during the deployment pipeline. | Yes |
-
-## Trigger
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `onCommit` | OnCommit | Configuration for triggering deployments upon new commits. | No |
-| `onCommand` | OnCommand | Configuration for triggering deployments via manual command. | No |
-| `onOutOfSync` | OnOutOfSync | Configuration for triggering deployments when drift is detected. | No |
-
-## PostSync
-
-| Field | Type | Description | Required |
-| --- | --- | --- | --- |
-| `chain` | []PostSyncPlugin | List of plugins or tasks to execute after a successful synchronization. | Yes |
+>**Note:**
+>PipeCD v1 documentation is still a work in progress. We are updating this configuration reference.
+> Until then, [see configurable fields for the application configuration file for v0.55](../../../docs-v0.55.x/user-guide/configuration-reference.md), and if you have any questions, [reach out to us](../../../../../../README.md#community-and-development) using one of our communication channels.
+>Happy PipeCDing!