PipeCD – Contribute

Docs-V0.56.x: Contribute to PipeCD

Mon, 01 Jan 0001 00:00:00 +0000

PipeCD is an open source project that anyone in the community can use, improve, and enjoy. We’d love you to join us!

Code of Conduct

PipeCD follows the CNCF Code of Conduct. Please read it to understand which actions are acceptable and which are not.

Ways to Contribute

There are many ways to contribute, and many don’t involve writing code:

Use PipeCD — Follow the Quickstart and report issues you encounter
Triage issues — Browse open issues, provide workarounds, ask for clarification, or suggest labels
Fix bugs — Issues labeled good first issue are great starting points
Improve docs — See Contribute to PipeCD Documentation
Participate in discussions — Share ideas in GitHub Discussions

Development Setup

Project Structure

PipeCD consists of several components:

Component	Description
cmd/pipecd	Control Plane — manages deployment data and provides gRPC API
cmd/piped	Piped agent — runs in your cluster
cmd/pipectl	Command-line tool
cmd/launcher	Command executor for remote upgrade
web	Web UI
docs	Documentation

Prerequisites

Go (check go.mod for version)
Node.js and Yarn (for web development)
Docker
kubectl
kind (Kubernetes in Docker)

Starting a Local Environment

1. Update Dependencies

make update/go-deps
make update/web-deps

Starting a local environment may fail if dependencies are not up to date.

2. Start Local Cluster and Registry

make up/local-cluster

This creates the pipecd Kubernetes namespace and starts a local registry.

To clean up later:

make down/local-cluster

3. Run Control Plane

make run/pipecd

To stop:

make stop/pipecd

4. Port Forward

In a separate terminal:

kubectl port-forward -n pipecd svc/pipecd 8080

5. Access the UI

Open http://localhost:8080?project=quickstart

Username: hello-pipecd
Password: hello-pipecd

Running Piped Agent

Ensure Control Plane is running and accessible.
Register a new Piped:
- Go to Settings → Piped (or http://localhost:8080/settings/piped?project=quickstart)
- Add a new piped and copy the generated Piped ID and base64 key

Create piped-config.yaml in the repository root:

Tip: Create a .dev folder (gitignored) for multiple config files.

apiVersion: pipecd.dev/v1beta1
kind: Piped
spec:
  projectID: quickstart
  pipedID: <YOUR_PIPED_ID>
  pipedKeyData: <YOUR_PIPED_BASE64_KEY>
  apiAddress: localhost:8080
  repositories:
    - repoId: example
      remote: git@github.com:pipe-cd/examples.git
      branch: master
  syncInterval: 1m
  platformProviders:
    - name: example-kubernetes
      type: KUBERNETES
      config:
        kubeConfigPath: /path/to/.kube/config

Start the Piped agent:

make run/piped CONFIG_FILE=path/to/piped-config.yaml INSECURE=true

Useful Commands

Check the Makefile for available commands. Common ones:

make check          # Run all checks (lint, test, etc.)
make test/go        # Run Go tests
make test/web       # Run web tests
make build/go       # Build Go binaries

Pull Request Process

Before You Start

Find or create an issue — Check if an issue exists, or open one for new features/bugs
Claim the issue — Comment “I’d like to work on this” to get assigned (expected to submit PR within 7 days)
Investigate first — Discuss your approach in the issue before coding to reduce back-and-forth on the PR
Focus on one issue — Especially for newcomers, work on one issue at a time

Submitting a Pull Request

Keep PRs small — Aim for ~300 lines of diff. Split larger changes into multiple PRs.
Use descriptive titles — Follow commit message style: present tense, capitalize first letter
```
Add imports to Terraform plan result
```
Sign off commits — Required for DCO compliance:
```
git commit -s -m "Your commit message"
```
Run checks before submitting:
```
make check
```
Target the master branch — All PRs should be opened against master

User-Facing Changes

If your change affects users, update the PR description:

**Does this PR introduce a user-facing change?**:
- **How are users affected by this change**:
- **Is this breaking change**:
- **How to migrate (if breaking change)**:

Licensing

By contributing, you agree to license your contributions under the Apache License Version 2.0. Add this header to new files:

// Copyright 2025 The PipeCD Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

Reporting Issues

Bugs

File bugs at GitHub Issues:

One issue, one bug
Provide reproduction steps — List all steps to reproduce the issue

Security Issues

Report security vulnerabilities privately via Slack or Twitter DM to maintainers listed in MAINTAINERS.md.

Feature Requests

Enhancement request — Improvements to existing features
Feature request — Entirely new features

Join the Community

Slack

We have a #pipecd channel on CNCF Slack for discussions and help. You can also assist other users in the channel.

Community Meetings

We host PipeCD Development and Community Meetings every 2 weeks where we share project news, demos, answer questions, and triage issues. View the Meeting Notes and Agenda.

Become a Member

If you’d like to join the pipe-cd GitHub organization:

Have at least 5 PRs merged to repositories in the pipe-cd organization
Attend a PipeCD public community meeting

Membership isn’t required to contribute—it’s for those who want to contribute long-term or take ownership of features.

What Happens Next?

The maintainers will review your PR. We’ll help with obvious issues and work with you to get it merged. Thank you for contributing!

Docs-V0.56.x: Architectural overview

Mon, 01 Jan 0001 00:00:00 +0000

Component Architecture

Piped

A single binary component runs in your cluster, your local network to handle the deployment tasks. It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment. This component is designed to be stateless, so it can also be run in a single VM or even your local machine.

Control Plane

A centralized component manages deployment data and provides gRPC API for connecting pipeds as well as all web-functionalities of PipeCD such as authentication, showing deployment list/details, application list/details, delivery insights…

Control Plane contains the following components:

server: a service to provide api for piped, web and serve static assets for web.
ops: a service to provide administrative features for Control Plane owner like adding/managing projects.
cache: a redis cache service for caching internal data.
datastore: data storage for storing deployment, application data
- this can be a fully-managed service such as Firestore, Cloud SQL…
- or a self-managed such as MySQL
filestore: file storage for storing logs, application states
- this can a fully-managed service such as GCS, S3…
- or a self-managed service such as Minio

For more information, see Architecture overview of Control Plane.

Docs-V0.56.x: Contribute to PipeCD Blogs

Mon, 01 Jan 0001 00:00:00 +0000

We welcome blog contributions from the community! Blog posts are a great way to share your experiences, tutorials, and insights about PipeCD with other users.

What makes a good blog post?

Blog posts can cover a variety of topics, including:

Announcements: New features, releases, or project updates
Tutorials: Step-by-step guides on using PipeCD features
Use cases: How you or your organization uses PipeCD
Best practices: Tips and tricks for getting the most out of PipeCD
Integrations: How to integrate PipeCD with other tools

Where blog posts live

Blog posts are located in the /docs/content/en/blog/ directory within the pipe-cd/pipecd repository.

Blog post format

Each blog post is a Markdown file with YAML front matter. Here’s the structure:

---
date: 2025-01-03
title: "Your Blog Post Title"
linkTitle: "Short Title for Navigation"
weight: 980
description: "A brief description of your post"
author: Your Name ([@your-github-handle](https://github.com/your-github-handle))
categories: ["Announcement"]
tags: ["Tag1", "Tag2"]
---

Your content here...

Front matter fields

Field	Required	Description
`date`	Yes	Publication date in `YYYY-MM-DD` format
`title`	Yes	Full title of your blog post
`linkTitle`	Yes	Shorter title used in navigation menus
`weight`	Yes	Controls ordering (lower = newer, typically use ~980-990)
`description`	No	Brief summary for SEO and previews
`author`	Yes	Your name with GitHub profile link
`categories`	Yes	One of: `Announcement`, `Tutorial`, `Release`
`tags`	No	Relevant keywords for your post

Content guidelines

Use clear, concise language
Include code examples where appropriate (use fenced code blocks with language identifiers)
Add images to /docs/static/images/ and reference them as ![alt text](/images/your-image.png)
Structure your post with headings (##, ###) for readability
Include a conclusion or summary section

How to submit your blog post

Fork and clone the pipecd repository
Create a branch for your blog post:
```
git checkout -b blog/your-post-title
```
Create your blog post file in /docs/content/en/blog/:
```
touch docs/content/en/blog/your-post-title.md
```
Add any images to /docs/static/images/
Preview locally by running:
```
make run/site
```
Then visit http://localhost:1313/blog/ to see your post.

Commit and push your changes:

git add .
git commit -s -m "blog: add post about your-topic"
git push origin blog/your-post-title

Open a Pull Request against the master branch

Review process

A maintainer will review your blog post for:

Technical accuracy
Clarity and readability
Adherence to the format guidelines
Appropriate use of images and code examples

Feel free to reach out on the #pipecd Slack channel if you have questions or want feedback on your draft before submitting.

Thank you for contributing to the PipeCD blog!

Docs-V0.56.x: Contribute to PipeCD Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Welcome! We are so happy you’re interested in helping improve our documentation. Your contributions make the project better for everyone.

This guide explains how you can contribute to the PipeCD Documentation, which resides on our official website, https://pipecd.dev.

Where to find the docs

Our documentation is located in the /docs folder within the pipe-cd/pipecd repository.

The content files are written in Markdown and live inside /docs/content/en/. You’ll notice two types of documentation folders:

/docs-dev/: This is for documentation related to unreleased, in-development features.
/docs-v0.x.x/ (and /docs-v1.0.x/): These folders contain the documentation for specific released versions of PipeCD.

How to build the docs locally

To preview your changes as you work, you must run the documentation website on your local machine.

Install Prerequisite: You must have the extended version of Hugo (v0.92.1 or higher) installed.
Run the Server: From the root of the pipecd repository, run the following command:
```
make run/site
```
Preview: Open your browser and go to http://localhost:1313 to see the live-reloading site.

How to submit your changes (The PR Process)

Create a Branch: Create a new branch for your changes (e.g., git checkout -b my-docs-fix).
Make Your Changes: Edit the necessary documentation files. If you are fixing an issue in the current documentation, remember to edit the file in both the /docs-dev/ and the latest /docs-vx.y.z/ folders.
Commit and Push: Commit your changes with a clear message and push your branch to your fork.
Open a Pull Request: Go to the PipeCD repository and open a Pull Request. In the description, please link to the issue you are fixing (e.g., Addresses #6124).
Review: A maintainer will review your PR, provide feedback, and merge it.

Thank you for contributing!