Plugin development resources

Note: This section is still a work in progress. A full tutorial and an in-docs translation of the Zenn book are planned over time.

For a hands-on walkthrough, read Build and learn PipeCD plugins (Zenn; Japanese title 作って学ぶ PipeCD プラグイン). The same book is linked again in Links, together with other references. Use your browser’s translate feature to read this in English. Verify commands and field names against this documentation and the pipecd repository.

Use this page together with Contribute to PipeCD plugins, which covers layout, make targets, and how to open a pull request.

How the pieces fit together

• Control plane: registers projects and piped agents; the web UI shows deployment status.
• piped: runs your plugins as separate binaries and talks to them over gRPC.
• Plugins: carry out deployments (and optionally live state and drift) for a platform or tool.

If you are new to PipeCD v1, read Plugins and Migrating from v0 to v1.

Terms

For plugin interfaces (Deployment, LiveState, Drift), see Plugin types. A first plugin usually implements Deployment only.

Local development

Use a piped v1 build that matches your work. From the repo you can run make run/piped as in the contributing guide. To install a release binary, see Installing on a single machine.

Example when running the v1 piped CLI:

./piped run --config-file=PATH_TO_PIPED_CONFIG --insecure=true

Use --insecure=true only when it matches your control plane (for example plain HTTP or your dev TLS settings).

The install guide linked above uses the same run subcommand. If another page or tutorial shows different syntax, run ./piped --help on your binary to match your build.

Older blog posts or books may target an older piped. Prefer this documentation and the default branch of pipecd.

piped config and application config

You need both:

1. piped configuration: control plane address, Git repositories, and spec.plugins (URL, port, deployTargets, plugin-specific fields). See Configuring a Plugin and Piped configuration reference.
2. Application configuration: the *.pipecd.yaml in Git (plugin, pipeline, deploy options). See Adding an application and Application configuration reference.

Code in your plugin reads the application config via its own types (often under config/). deployTargets come from the piped config.

Example plugins

Cache under ~/.piped

After rebuilding a plugin, piped may still use files under ~/.piped (including ~/.piped/plugins). If your changes do not show up, remove those directories or clear the cache your team uses, then restart piped.

Debugging

• Web UI: deployment and stage status.
• Stdout: logs from piped and the plugin (verbose but quick for local work).
• Stage logs: through the SDK; see StageLogPersister in the repo.

Links

See also Contributing to PipeCD for local control plane setup and pull requests.