pipe-cd · kubeboiii · Jun 10, 2026 · Jul 19, 2026
@@ -0,0 +1,82 @@
+# PipeCD Dev Container
+
+Development container configuration for [GitHub Codespaces](https://github.com/features/codespaces) and VS Code [Dev Containers](https://containers.dev/).
+
+Tool versions match CI where applicable: Go 1.26.2, Node 20.19.0, Helm 3.8.2.
+
+## Prerequisites
+
+- Docker available on the host (Docker Desktop, OrbStack, or Codespaces built-in Docker).
+- For VS Code: install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.
+
+## Open the environment
+
+### GitHub Codespaces
+
+Create a codespace from this repository. A machine with at least 4 CPU and 16 GB RAM is recommended if you plan to run a local kind cluster.
+
+### VS Code
+
+1. Open this repository folder in VS Code.
+2. Run **Dev Containers: Reopen in Container** from the command palette.
+3. Wait for the image build and `post-create.sh` to finish.
+
+Setup runs `make update/go-deps` and `make update/web-deps` automatically.
+
+## Verify the environment
+
+```bash
+docker info
+go version
+make build/go
+```
+
+## Optional: local Kubernetes cluster and control plane
+
+These steps use the same Makefile targets as a manual local setup. They are optional and not required to build or test Go code.
+
+```bash
+make up/local-cluster
+kind export kubeconfig --name pipecd
+kubectl get nodes
+make run/pipecd
+kubectl port-forward -n pipecd svc/pipecd 8080
+```
+
+Open `http://localhost:8080?project=quickstart` and sign in with username `hello-pipecd` and password `hello-pipecd`.
+
+The `pipecd` namespace is created when you run `make run/pipecd`, not by `make up/local-cluster`.
+
+Cleanup:
+
+```bash
+make down/local-cluster
+```
+
+## Known limitations
+
+- Docker runs on the host via socket mount (Docker-outside-of-Docker). Rootless-only Docker setups are not supported.
+- `make lint/go` and `make gen/code` use Docker on the host, same as a normal local setup.
+- `make run/pipecd` builds a linux/amd64 image. This matches the existing Makefile behavior.
+- A local kind cluster may be slow or fail to start on some host setups (for example OrbStack on Apple Silicon inside a dev container). If `make up/local-cluster` fails, try GitHub Codespaces or run cluster commands on the host. Pushing to `localhost:5001` has been verified from inside the dev container.
+- Gitpod is not configured yet. See CONTRIBUTING.md.
+
+## Troubleshooting
+
+### `make up/local-cluster` fails with connection refused on port 6443
+
+kind could not start the Kubernetes API server in time. Try:
+
+1. `make down/local-cluster` and run `make up/local-cluster` again.
+2. Allocate more memory to Docker (8 GB minimum, 16 GB recommended).
+3. Use GitHub Codespaces instead of a local dev container.
+
+### Stale kind cluster or registry
+
+```bash
+make down/local-cluster
+kind delete cluster --name pipecd 2>/dev/null || true
+docker rm -f kind-registry 2>/dev/null || true
+```
+
+Then run `make up/local-cluster` again.
@@ -0,0 +1,24 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+      "version": "1.10.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-outside-of-docker@sha256:c2c2cf829505ead8e4892c88c31b6594ae94a2bbb209e16e1fac456c1a3a624e",
+      "integrity": "sha256:c2c2cf829505ead8e4892c88c31b6594ae94a2bbb209e16e1fac456c1a3a624e"
+    },
+    "ghcr.io/devcontainers/features/go:1": {
+      "version": "1.3.4",
+      "resolved": "ghcr.io/devcontainers/features/go@sha256:d85e921f91b41340055bb12b325d9d551170ed04b3b832e33530bf42f167c032",
+      "integrity": "sha256:d85e921f91b41340055bb12b325d9d551170ed04b3b832e33530bf42f167c032"
+    },
+    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {
+      "version": "1.3.1",
+      "resolved": "ghcr.io/devcontainers/features/kubectl-helm-minikube@sha256:bbe8adf6b37fff8c67412ab0a4579f4c2f30bbaba1d9a5cebd9e38bade54025b",
+      "integrity": "sha256:bbe8adf6b37fff8c67412ab0a4579f4c2f30bbaba1d9a5cebd9e38bade54025b"
+    },
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "1.7.1",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6",
+      "integrity": "sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6"
+    }
+  }
+}
@@ -0,0 +1,33 @@
+{
+  "name": "PipeCD",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "features": {
+    "ghcr.io/devcontainers/features/go:1": {
+      "version": "1.26.2"
+    },
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "20.19.0"
+    },
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+      "moby": false,
+      "dockerDashComposeVersion": "v2"
+    },
+    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {
+      "version": "v1.32.2",
+      "helm": "3.8.2",
+      "minikube": "none"
+    }
+  },
+  "forwardPorts": [8080, 9090],
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "remoteUser": "vscode",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "golang.go",
+        "dbaeumer.vscode-eslint",
+        "ms-kubernetes-tools.vscode-kubernetes-tools"
+      ]
+    }
+  }
+}
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Copyright 2026 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.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${REPO_ROOT}"
+
+kind_arch() {
+  case "$(uname -m)" in
+    x86_64) echo "amd64" ;;
+    aarch64 | arm64) echo "arm64" ;;
+    *)
+      echo "unsupported architecture for kind: $(uname -m)" >&2
+      return 1
+      ;;
+  esac
+}
+
+install_kind() {
+  local kind_version="v0.27.0"
+  local arch
+  arch="$(kind_arch)"
+  local kind_bin="/tmp/kind"
+  curl -fsSL "https://kind.sigs.k8s.io/dl/${kind_version}/kind-linux-${arch}" -o "${kind_bin}"
+  chmod +x "${kind_bin}"
+  sudo mv "${kind_bin}" /usr/local/bin/kind
+}
+
+setup_yarn() {
+  if command -v yarn >/dev/null 2>&1; then
+    return
+  fi
+
+  if command -v corepack >/dev/null 2>&1; then
+    corepack enable
+    corepack prepare yarn@1.22.22 --activate
+    return
+  fi
+
+  npm install -g yarn
+}
+
+echo "Installing kind..."
+install_kind
+
+echo "Setting up Yarn..."
+setup_yarn
+
+echo "Updating Go dependencies..."
+make update/go-deps
+
+echo "Updating web dependencies..."
+make update/web-deps
+
+echo "Running smoke checks..."
+docker info >/dev/null
+go version
+node --version
+yarn --version
+helm version --short
+kubectl version --client=true
+kind version
+
+echo "Dev container setup complete."
@@ -194,9 +194,9 @@ Run `make update/go-deps` and `make update/web-deps` to update the dependencies.

 In order to start a local development environment, a registry needs to be running locally.

-Run `make up/local-cluster` to start a local registry.
+Run `make up/local-cluster` to start a local registry and a kind cluster.

-This will create the kubernetes namespace `pipecd` if it does not exist and start a local registry in the namespace which can then be accessed by other components.
+The `pipecd` Kubernetes namespace is created when you run `make run/pipecd`, not by `make up/local-cluster`.

 When cleaning up, run `make down/local-cluster` to stop and delete the registry and the cluster.

@@ -272,7 +272,19 @@ Replace `path/to/piped-config.yaml` with the actual path to your configuration f

 ### Online one-click setup for contributing

-We are preparing Gitpod and Codespace to facilitate the setup process for contributing.
+You can use a [Dev Container](https://containers.dev/) to open PipeCD in GitHub Codespaces or VS Code with Go, Node, Docker, kubectl, kind, and Helm pre-installed.
+
+1. Open this repository in **GitHub Codespaces** or VS Code with the **Dev Containers** extension.
+2. Wait for the container to build. Setup runs `make update/go-deps` and `make update/web-deps` automatically.
+3. Verify the environment:
+
+```bash
+make build/go
+```
+
+4. For a local Kubernetes cluster and control plane, follow [.devcontainer/README.md](./.devcontainer/README.md).
+
+We are still preparing Gitpod support.

 ## Contributor License Agreement