From b993d3ad0407226c60e2e1b1b79d35e06abf9aea Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Tue, 11 Aug 2026 19:27:19 +0530 Subject: [PATCH 1/3] docs: add plugin tutorial chapter 2 - setup, plugin types, and project scaffold Signed-off-by: rahulshendre --- ...setup-plugin-types-and-project-scaffold.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md diff --git a/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md new file mode 100644 index 0000000000..1f00edd81f --- /dev/null +++ b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md @@ -0,0 +1,66 @@ +--- +title: "Setup, plugin types, and project scaffold" +linkTitle: "Setup, plugin types, and project scaffold" +weight: 2 +description: > + Create the project, add the plugin SDK, and learn which plugin type you build. +--- + +In this chapter you create the project for the file plugin, add the plugin SDK, and learn where the plugin fits among the SDK's plugin types. By the end you have a Go module with the SDK in place, ready for the code you write in the following chapters. + +## Set up the project + +The plugin is a normal Go module. Create a directory for it, initialize a Git repository, and create the Go module: + +```bash +git init pipecd-plugin-file +cd pipecd-plugin-file +go mod init github.com//pipecd-plugin-file +``` + +Replace `` with your GitHub account name, or use any module path you prefer. The plugin builds with Go 1.26 or later, matching the version the official plugins use. + +Commit as you go. This tutorial does not point out every commit from here on, but small, frequent commits make it easy to retrace your own steps. + +## Add the plugin SDK + +Plugins are built with the official plugin SDK ([`github.com/pipe-cd/piped-plugin-sdk-go`](https://pkg.go.dev/github.com/pipe-cd/piped-plugin-sdk-go)). Add it to the module: + +```bash +go get github.com/pipe-cd/piped-plugin-sdk-go@v0.4.0 +``` + +The SDK provides the plugin server, the interfaces you implement, and the request and response types that `piped` sends and expects. Apart from the SDK, the file plugin uses only the Go standard library. + +## Plugin types + +`piped` does not define separate kinds of plugins on its own. For convenience, the SDK groups plugins by the interface they implement: + +- **StagePlugin** provides stages that are useful during a deployment but has nothing of its own to deploy. The `wait` plugin, which pauses a pipeline for a set time, is a StagePlugin. +- **DeploymentPlugin** has something to deploy and syncs it. The `kubernetes` plugin is a DeploymentPlugin. A DeploymentPlugin also provides everything a StagePlugin does. +- **LivestatePlugin** reports the live state of deployed resources, so the web UI can show the difference between what is running and what is defined in Git. It is often implemented alongside a DeploymentPlugin. + +The file plugin treats copying files as its deployment, so it is a **DeploymentPlugin**. + +## The DeploymentPlugin interface + +A DeploymentPlugin has three type parameters. They let the SDK decode configuration into types that you define: + +- **Config** is configuration shared across the plugin, written in the `piped` configuration. +- **DeployTargetConfig** is configuration for a single deploy target, such as the connection details for a cluster. +- **ApplicationConfigSpec** is per-application configuration, such as the files an application deploys. + +The file plugin needs neither plugin-wide nor deploy-target configuration, so its Config and DeployTargetConfig are empty. You define all three types in the next chapter. + +To satisfy the DeploymentPlugin interface, you implement the following methods: + +```go +FetchDefinedStages() []string +DetermineVersions(context.Context, *Config, *DetermineVersionsInput[ApplicationConfigSpec]) (*DetermineVersionsResponse, error) +DetermineStrategy(context.Context, *Config, *DetermineStrategyInput[ApplicationConfigSpec]) (*DetermineStrategyResponse, error) +BuildPipelineSyncStages(context.Context, *Config, *BuildPipelineSyncStagesInput) (*BuildPipelineSyncStagesResponse, error) +BuildQuickSyncStages(context.Context, *Config, *BuildQuickSyncStagesInput) (*BuildQuickSyncStagesResponse, error) +ExecuteStage(context.Context, *Config, []*DeployTarget[DeployTargetConfig], *ExecuteStageInput[ApplicationConfigSpec]) (*ExecuteStageResponse, error) +``` + +You implement these across the next several chapters, starting from the top. For now the project is set up and the SDK is in place, so the next chapter defines the configuration types and writes an empty implementation that satisfies this interface. From 54a5026d70d6e534f2d364e88d57126c0804cc91 Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Thu, 13 Aug 2026 13:22:30 +0530 Subject: [PATCH 2/3] docs: link config types to ch 3 Signed-off-by: rahulshendre --- .../chapter-02-setup-plugin-types-and-project-scaffold.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md index 1f00edd81f..84c55d32cc 100644 --- a/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md +++ b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md @@ -50,7 +50,7 @@ A DeploymentPlugin has three type parameters. They let the SDK decode configurat - **DeployTargetConfig** is configuration for a single deploy target, such as the connection details for a cluster. - **ApplicationConfigSpec** is per-application configuration, such as the files an application deploys. -The file plugin needs neither plugin-wide nor deploy-target configuration, so its Config and DeployTargetConfig are empty. You define all three types in the next chapter. +The file plugin needs neither plugin-wide nor deploy-target configuration, so its Config and DeployTargetConfig are empty. You define all three types in the [next chapter](../chapter-03-config-types-and-empty-implementation/#define-the-configuration-types). To satisfy the DeploymentPlugin interface, you implement the following methods: From eae59fed42caa953cfa02392f33e8ebf99dc9d9b Mon Sep 17 00:00:00 2001 From: rahulshendre Date: Tue, 25 Aug 2026 13:11:27 +0530 Subject: [PATCH 3/3] docs: mention PlanPreviewPlugin in plugin types section Signed-off-by: rahulshendre --- .../chapter-02-setup-plugin-types-and-project-scaffold.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md index 84c55d32cc..89b0548da0 100644 --- a/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md +++ b/docs/content/en/docs-v1.0.x/plugins/creating-a-plugin/chapter-02-setup-plugin-types-and-project-scaffold.md @@ -40,6 +40,8 @@ The SDK provides the plugin server, the interfaces you implement, and the reques - **DeploymentPlugin** has something to deploy and syncs it. The `kubernetes` plugin is a DeploymentPlugin. A DeploymentPlugin also provides everything a StagePlugin does. - **LivestatePlugin** reports the live state of deployed resources, so the web UI can show the difference between what is running and what is defined in Git. It is often implemented alongside a DeploymentPlugin. +- **PlanPreviewPlugin** returns a plan preview for an application (for example, a Terraform plan/diff shown before applying changes). + The file plugin treats copying files as its deployment, so it is a **DeploymentPlugin**. ## The DeploymentPlugin interface