blog: implement contributor guide for local PipeCD setup #6375

shivansh-gohem · 2025-12-11T18:51:58Z

This PR delivers the local setup guide you assigned.

Goal: Create a simple, step-by-step tutorial for new contributors on setting up the Control Plane and Piped agent locally via the Quickstart method.

Source: The guide is based on the official quickstart and my personal successful end-to-end setup (validated in PR #6332).

Ready for review! Thank you.

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>

eeshaanSA

Thanks for this, @shivansh-gohem. You seem to have mistaken the local development setup with the quick start guide.

The quickstart setup is aimed towards end-users who want to setup PipeCD and try the features out. The actual development setup would be ideally done through the source code, forked from GitHub. Please check how to setup a local development environment documentation on GitHub.

shivansh-gohem · 2025-12-12T13:03:18Z

Hi @eeshaanSA,

Thank you again for the critical feedback. I sincerely apologize for the initial error confusing the End-User Quickstart with the Contributor Local Development Setup.

I have located the correct documentation and have completely rewritten the blog post.

The PR now contains a guide focused on the correct developer workflow: building and running the Control Plane and Piped Agent directly from the Go source code (using make run/pipecd and make run/piped), which is the true path for contribution.

eeshaanSA · 2025-12-12T19:30:39Z

docs/content/en/blog/local-setup-contributor-guide.md

+
+## 1. Prepare and Start the Local Cluster
+
+First, update dependencies and set up a local registry and cluster for the control plane to use.


We need more info on "How to" do this.

eeshaanSA · 2025-12-12T19:34:48Z

docs/content/en/blog/local-setup-contributor-guide.md

+tags: ["Local Development", "Go", "Kubernetes", "Dev Setup"]
+---
+
+## Why a Local Development Environment is Essential


Need a better title

eeshaanSA · 2025-12-12T19:36:46Z

docs/content/en/blog/local-setup-contributor-guide.md

+
+Make sure you have:
+
+- Go (v1.21 or higher)
+- Docker
+- kubectl
+- PipeCD repository cloned locally:
+
+git clone https://github.com/pipe-cd/pipecd.git
+cd pipecd


It is essential to create a fork of the target repository in order to make successful open source contributions. This is highly inaccurate

eeshaanSA · 2025-12-12T19:37:36Z

@shivansh-gohem, have you tried setting up PipeCD using this guide?

shivansh-gohem · 2025-12-13T19:01:15Z

Hi @eeshaanSA ,
Yes, I have set up PipeCD locally using these developer steps.

I verified the full build process locally (make run/pipecd). The build revealed that Node.js and Yarn were missing from the prerequisites list (causing the web build to fail). I have updated the guide to include them, along with the correct make update/web-deps command.

I also fixed the Fork instruction and the Title as requested. The PR is now ready for review

shivansh-gohem · 2025-12-18T18:16:12Z

Hi @eeshaanSA,

Just a gentle bump on this PR. I believe I have addressed all the feedback from your last review (updated the title, corrected the fork instructions, and verified the local setup steps including the Yarn dependencies).

Please let me know if there are any further changes needed. Thank you!

eeshaanSA · 2025-12-19T20:29:16Z

docs/content/en/blog/local-setup-contributor-guide.md

+2. Click **+ ADD**, give it a name (for example, `dev`), and save.  
+3. **Crucial step:** Copy the generated **Piped ID** and **Base64 encoded key** immediately.
+
+### Create the Piped configuration


we need a v1 pipedConfig example here too now, which might be a little complicated.

shivansh-gohem · 2025-12-20T16:18:21Z

Hi @eeshaanSA,

Thank you for testing this out and for the honest feedback.

I understand that the local development setup has some underlying stability issues right now and that the shift to the v1 pipedConfig adds complexity. I appreciate you saving me from spinning my wheels on this while those architectural changes are discussed. I will put this PR on hold.

Since I have been focusing on [EPIC] Improve and Expand Contributing Section in Documentation #6124, I would love to stay within that scope if possible.

I know I previously mentioned tackling the 'Contribute to piped Plugins' section next. Is that area also blocked by the v1 config issues (since it requires a local agent), or would that be a safe documentation task to pick up now?

shivansh-gohem · 2025-12-29T13:48:42Z

/cc @eeshaanSA

shivansh-gohem · 2026-01-02T13:25:39Z

Hi @eeshaanSA,

I have re-verified the setup locally with a clean cluster on the latest master.

make up/local-cluster: Success

make run/pipecd: Success (All pods healthy: server, gateway, ops are Running)

UI Access: Success

The stability issues are resolved. Ready for merge!

eeshaanSA · 2026-01-03T08:18:15Z

Please resolve the issues in the PR, and please, avoid submitting low quality PRs if you want your PRs to be merged soon.

shivansh-gohem · 2026-01-04T18:49:05Z

Thanks for the feedback. I checked the pkg/config/testdata and realized I had a typo in the config kind (Pipecd instead of Piped).

I have corrected the guide to use the valid apiVersion: pipecd.dev/v1beta1 and kind: Piped structure. The PR is now updated and squashed. Ready for review.

eeshaanSA

Please resolve the comments, and the changes requested. Additionally, title needs to be changed.

eeshaanSA

Please resolve the comments and implement the changes. Additionally, we need a better title. "How to set-up..."

eeshaanSA · 2026-01-05T08:33:49Z

@rahulshendre, @Ayushmore1214

Would you mind reviewing this PR? Your help would be appreciated.

Ayushmore1214 · 2026-01-05T10:37:01Z

@shivansh-gohem Also according to the steps mentioned in the doc the local dev server doesnt seems to be starting , are you sure you tried running on your env , does it works fine ? I am using github codespaces Btw

eeshaanSA · 2026-01-05T10:49:15Z

@shivansh-gohem Also according to the steps mentioned in the doc the local dev server doesnt seems to be starting , are you sure you tried running on your env , does it works fine ? I am using github codespaces Btw

interesting, could you please share screenshots, and also try the setup on CONTRIBUTING.md please?

eeshaanSA · 2026-01-05T10:49:49Z

Don't know about GitHub workspaces, but it should work in a local env.

rahulshendre

@shivansh-gohem the “Context” heading feels a bit out of place here. The content reads more like a summary or an introduction to the next step rather than background context. Renaming it to something like “Next Steps” would be better.
@eeshaanSA, could you suggest a good replacement.

Ayushmore1214 · 2026-01-05T11:08:51Z

@shivansh-gohem Also according to the steps mentioned in the doc the local dev server doesnt seems to be starting , are you sure you tried running on your env , does it works fine ? I am using github codespaces Btw

interesting, could you please share screenshots, and also try the setup on CONTRIBUTING.md please?

Seems to be working now , a silly mistake by me

Ayushmore1214 · 2026-01-05T09:17:39Z

docs/content/en/blog/local-setup-contributor-guide.md

+tags: ["Local Development", "Go", "Kubernetes", "Dev Setup"]
+---
+
+## Why a Local Development Environment is Essential


"Local Development Setup for PipeCD Contributors" , you can use this as title

Ayushmore1214 · 2026-01-05T09:21:21Z

docs/content/en/blog/local-setup-contributor-guide.md

+```
+## 1. Prepare and Start the Local Cluster
+
+First, update dependencies and set up a local registry and cluster for the control plane to use.


"This step prepares a local Kubernetes cluster and container registry required for running the PipeCD control plane locally" , this would fit in good here

Ayushmore1214 · 2026-01-05T11:13:34Z

docs/content/en/blog/local-setup-contributor-guide.md

+If you plan to contribute code, fix bugs, or add new plugins to PipeCD, you should run the control plane and Piped agent directly from the source code. This local development setup lets you test your Go changes live before submitting a pull request.
+
+This guide walks through building and running the components from source so you can iterate quickly and confidently.
+


"Estimated setup time: 20–30 minutes" we can also add this , should we @eeshaanSA ?

+1 to this. Adding an estimated setup time would set expectations for new contributors.

@shivansh-gohem lets add the estimated time one here rather than on top

Thanks @Ayushmore1214! I have moved the 'Estimated setup time' line down to the position you requested (after the intro, before Prerequisites).

rahulshendre · 2026-01-05T11:51:18Z

docs/content/en/blog/local-setup-contributor-guide.md

+
+Use your local code and the config file you just created:
+```bash
+make run/piped CONFIG_FILE=piped-config.yaml


In the Piped run command you seem to have missed INSECURE=true.
The official CONTRIBUTING.md mentions it, and without it the connection fails

shivansh-gohem · 2026-01-05T14:16:04Z

Thanks everyone! I have updated the PR with all requests:

Title & Metadata: Updated title to 'How to set up...' and filled in the Frontmatter with valid details.

Content Updates: Added 'Estimated setup time', updated the Step 1 description, and removed the inaccurate note on forking.

Corrections: Added INSECURE=true to the run command and renamed the final section to 'Next Steps'.

Ready for final review.

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>

Ayushmore1214

Looks good to me 👍

docs: add 'Contribute to PipeCD Blogs' guide

c652eb7

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>

shivansh-gohem requested a review from a team as a code owner December 11, 2025 18:51

shivansh-gohem requested review from Warashi, khanhtc1202 and t-kikuc December 11, 2025 18:51

eeshaanSA suggested changes Dec 11, 2025

View reviewed changes

shivansh-gohem force-pushed the blog-local-setup-guide branch from 8eab5b6 to 6b3b822 Compare December 12, 2025 13:01

eeshaanSA suggested changes Dec 12, 2025

View reviewed changes

shivansh-gohem force-pushed the blog-local-setup-guide branch from 6b3b822 to 61618b5 Compare December 13, 2025 18:59

eeshaanSA suggested changes Dec 19, 2025

View reviewed changes

shivansh-gohem mentioned this pull request Dec 29, 2025

[EPIC] Improve and Expand Contributing Section in Documentation #6124

Open

shivansh-gohem force-pushed the blog-local-setup-guide branch from 61618b5 to f0a9525 Compare January 4, 2026 18:48

eeshaanSA mentioned this pull request Jan 5, 2026

docs: add 'Contribute to PipeCD Blogs' guide #6353

Open

eeshaanSA approved these changes Jan 5, 2026

View reviewed changes

eeshaanSA suggested changes Jan 5, 2026

View reviewed changes

rahulshendre reviewed Jan 5, 2026

View reviewed changes

Ayushmore1214 suggested changes Jan 5, 2026

View reviewed changes

rahulshendre reviewed Jan 5, 2026

View reviewed changes

shivansh-gohem force-pushed the blog-local-setup-guide branch from f0a9525 to 715165a Compare January 5, 2026 14:14

blog: add guide on how to set up local development environment

bc73eeb

Signed-off-by: Shivansh Sahu <sahushivansh142@gmail.com>

shivansh-gohem force-pushed the blog-local-setup-guide branch from 715165a to bc73eeb Compare January 5, 2026 19:05

Ayushmore1214 approved these changes Jan 6, 2026

View reviewed changes


		## 1. Prepare and Start the Local Cluster

		First, update dependencies and set up a local registry and cluster for the control plane to use.

		If you plan to contribute code, fix bugs, or add new plugins to PipeCD, you should run the control plane and Piped agent directly from the source code. This local development setup lets you test your Go changes live before submitting a pull request.

		This guide walks through building and running the components from source so you can iterate quickly and confidently.

blog: implement contributor guide for local PipeCD setup #6375

Are you sure you want to change the base?

blog: implement contributor guide for local PipeCD setup #6375

Conversation

shivansh-gohem commented Dec 11, 2025

Uh oh!

eeshaanSA left a comment

Choose a reason for hiding this comment

Uh oh!

shivansh-gohem commented Dec 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eeshaanSA commented Dec 12, 2025

Uh oh!

shivansh-gohem commented Dec 13, 2025

Uh oh!

shivansh-gohem commented Dec 18, 2025

Uh oh!

eeshaanSA Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivansh-gohem commented Dec 20, 2025

Uh oh!

shivansh-gohem commented Dec 29, 2025

Uh oh!

shivansh-gohem commented Jan 2, 2026

Uh oh!

eeshaanSA commented Jan 3, 2026

Uh oh!

shivansh-gohem commented Jan 4, 2026

Uh oh!

eeshaanSA left a comment

Choose a reason for hiding this comment

Uh oh!

eeshaanSA left a comment

Choose a reason for hiding this comment

Uh oh!

eeshaanSA commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ayushmore1214 commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eeshaanSA commented Jan 5, 2026

Uh oh!

eeshaanSA commented Jan 5, 2026

Uh oh!

rahulshendre left a comment

Choose a reason for hiding this comment

Uh oh!

Ayushmore1214 commented Jan 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shivansh-gohem commented Jan 5, 2026

Uh oh!

Ayushmore1214 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

eeshaanSA Dec 19, 2025 •

edited

Loading

eeshaanSA commented Jan 5, 2026 •

edited

Loading

Ayushmore1214 commented Jan 5, 2026 •

edited

Loading