Add Helm chart with full component support and docs by nissessenap · Pull Request #45 · nissessenap/shepherd

nissessenap · 2026-03-03T21:32:45Z

Summary

Helm chart for all Shepherd components (operator, API server, web frontend, GitHub adapter) with OCI registry publishing (ghcr.io/nissessenap/helm-charts/shepherd)
CRDs managed via templates/ with helm.sh/resource-policy: keep so they upgrade with the chart but survive uninstall
GitHub adapter as an optional component (githubAdapter.enabled: false by default) with full secret mounting and callback configuration
Production features: PodDisruptionBudgets, HorizontalPodAutoscalers, configurable security contexts, RBAC, and extraObjects for arbitrary additional resources
values-quickstart.yaml for local Kind development with NodePort services (30080/30081) and 1 replica
Helm-first documentation: quickstart and deployment guide rewritten to use helm install with released OCI images instead of kustomize/ko
Helm values reference page symlinked into Hugo docs site from the helm-docs generated README.md
Release workflow updated with OCI chart publish job

Details

Chart structure

charts/shepherd/
├── Chart.yaml
├── README.md / README.md.gotmpl     # helm-docs generated
├── values.yaml                       # full defaults
├── values-quickstart.yaml            # Kind dev overrides
├── files/
│   ├── crds/                         # AgentTask CRD YAML
│   └── rbac.yaml                     # Operator ClusterRole rules
└── templates/
    ├── _helpers.tpl                   # naming, labels, image helpers
    ├── crds.yaml                      # CRD installer
    ├── extraobjects.yaml              # user-supplied extra resources
    ├── api/                           # API server (deploy, svc, sa, rbac, hpa, pdb)
    ├── operator/                      # Operator (deploy, sa, rbac)
    ├── web/                           # Web frontend (deploy, svc, sa, configmap-nginx, hpa, pdb)
    └── github-adapter/                # GitHub adapter (deploy, svc, sa, hpa, pdb)

Documentation changes

Quickstart: Prerequisites reduced to Docker, Kind, kubectl, Helm (no more ko, Go, Node.js). Uses official agent-sandbox release manifests, inline SandboxTemplate, and helm install from OCI registry
Deployment guide: Helm-based production guide replacing all kustomize content. Five clear steps: agent-sandbox → secrets → SandboxTemplate → Helm install → verify
Helm values page: Symlink from docs/content/docs/setup/helm-values.md to the generated chart README with Hugo frontmatter

Test plan

helm template test charts/shepherd/ renders without errors
helm template test charts/shepherd/ -f charts/shepherd/values-quickstart.yaml --set githubAdapter.enabled=false renders NodePort services, no adapter
helm template test charts/shepherd/ -f charts/shepherd/values-quickstart.yaml renders all components including adapter
hugo --minify in docs/ builds successfully with the new symlinked page
make helm-docs regenerates README.md with frontmatter
Deploy to Kind cluster with values-quickstart.yaml and verify pods come up

🤖 Generated with Claude Code

Adds deployment, service, and serviceaccount templates for the GitHub adapter, disabled by default. When enabled, mounts GitHub App credentials from an existing secret and connects to the API internal port. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…m-values page - Add Hugo frontmatter to README.md.gotmpl so generated README works as a Hugo page - Create symlink docs/setup/helm-values.md → charts/shepherd/README.md - Add values-quickstart.yaml with 1 replica, NodePort extraObjects for Kind - Rewrite quickstart to use Helm + released images (removed ko/Go/Node.js prereqs) - Rewrite deployment guide as Helm-based, remove all kustomize content Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nissessenap

Minor comments

nissessenap · 2026-03-03T22:10:16Z

+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  replicas: {{ .Values.api.replicas }}


If hpa enabled we shouldn't say replicas.

nissessenap · 2026-03-03T22:13:13Z

+        - name: api
+          securityContext:
+            {{- toYaml .Values.api.securityContext | nindent 12 }}
+          image: {{ include "shepherd.image" (dict "service" .Values.api.image "global" .Values.global.image "defaultVersion" .Chart.AppVersion) }}


Do we build repo and registry? If not we should

nissessenap · 2026-03-03T22:19:35Z

+          {{- end }}
+          volumeMounts:
+            - name: nginx-config
+              mountPath: /etc/nginx/conf.d/nginx.default.conf


Is it really /etc since we are running rootless image from chainguard?

nissessenap · 2026-03-03T22:21:25Z

+            - name: nginx-tmp
+              mountPath: /var/lib/nginx/tmp
+            - name: nginx-run
+              mountPath: /var/run


I assume this is needed due to not allowing to write to root. Are we sure that is how chainguard works + is path correct?

nissessenap · 2026-03-03T22:23:59Z

+# values-quickstart.yaml — Local Kind development only. DO NOT use in production.
+#
+# Usage:
+#   Part 1 (no GitHub):


Nit why is part 1 without GitHub? Call it no GitHub or similar, don't mention part

nissessenap · 2026-03-03T22:27:11Z

+  pdb:
+    # -- Enable PodDisruptionBudget for the API
+    enabled: false
+    # -- Minimum available pods (mutually exclusive with maxUnavailable)


Add a note that hpa/replica count always have to be +1 compared to minimum pdb. Or stuff will hang

nissessenap · 2026-03-03T22:29:28Z

+nodes:
+- role: control-plane
+  extraPortMappings:
+  - containerPort: 30080


We should have a nodeport for GitHub as well, the majority of users want to have it

nissessenap · 2026-03-03T22:32:26Z

 ```

-The test overlay deploys all Shepherd components with NodePort services and **no GitHub App requirement**. This is the fastest way to explore the system.
+Install Shepherd without the GitHub adapter:


Show how to do it with GitHub adapter

nissessenap · 2026-03-03T22:34:20Z

 ---

-This guide covers deploying Shepherd to a Kubernetes cluster. If you're looking to run locally for development, see the [Quickstart](../../getting-started/quickstart/) instead.
+This guide covers deploying Shepherd to a Kubernetes cluster with Helm. If you're looking to run locally for development, see the [Quickstart](../../getting-started/quickstart/) instead.


For a quick test. For development they should read contributing

nissessenap · 2026-03-03T22:37:18Z

-
-```bash
-kubectl apply -f config/samples/sandbox-template-runner.yaml -n shepherd-system
+EOF


We should add info that it's possible to do warm agent as well

…arnings - Omit spec.replicas when HPA is enabled to prevent scale fights on helm upgrade - Fix Chainguard nginx mount paths: /var/run → /run (pid), add /var/log/nginx - Add PDB minAvailable + replicas warning to all three component sections - Add GitHub adapter NodePort (30082) to quickstart values and Kind config - Show helm install with GitHub adapter in quickstart docs - Rename Part 1/Part 2 to descriptive headings (no GitHub / with GitHub) - Fix deployment guide: quick test vs development (link to CONTRIBUTING.md) - Add warm sandbox callout to deployment guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nissessenap and others added 8 commits March 3, 2026 20:52

helm

3552f7b

chart part what ever

4cef807

phase 5

70f7013

Add PDB and HPA resources for API, web, and GitHub adapter (Phase 7)

bf9b5ee

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add extraObjects, helm-docs README, and final polish (Phase 8)

ba6f2c6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add Helm chart OCI publish job to release workflow

f15bab9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

nissessenap commented Mar 3, 2026

View reviewed changes

nissessenap merged commit 187f362 into main Mar 4, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Helm chart with full component support and docs#45

Add Helm chart with full component support and docs#45
nissessenap merged 9 commits into
mainfrom
helm

nissessenap commented Mar 3, 2026

Uh oh!

nissessenap left a comment

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

nissessenap Mar 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

nissessenap commented Mar 3, 2026

Summary

Details

Chart structure

Documentation changes

Test plan

Uh oh!

nissessenap left a comment

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!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant