deployment

name	deployment
description	Use this skill for a Helm-upgrade deploy of an app service (the web portal or the edge service) to an EXISTING Kubernetes cluster, plus post-deploy verification. NOT for cluster-level ops -- Minikube/k3s lifecycle, GCP firewall, tunnels, bootstrap secrets (use kubernetes-deployment); NOT for cross-environment promotion (use release-promotion).
version	1.0.0
owner	swarmery-infra
docs	{"status":"reviewed","source_sha":"4112200c69a3","updated":"2026-08-06T00:00:00.000Z"}

Purpose

Orchestrate the project's service deployments across local-dev (Minikube), the staging environment (project.json → cloud.envAlias; typically a cloud VM + Minikube), and production (e.g. edge device + k3s) using Helm, producing a deploy status report with pod health and endpoint verification. This skill covers the single-environment deploy-and-verify cycle; it defers image building to docker-build, chart template authoring to helm-chart-expert, and cross-environment promotion to release-promotion.

When to use this skill

• Trigger A -- Deploying a Helm release to any single project environment
• Trigger B -- Running post-deployment verification (pod health, endpoint checks, ingress validation)
• Trigger C -- Rolling back a failed Helm release within the same environment
• Trigger D -- Inspecting current deploy state (helm list, helm history, pod status)

When NOT to use this skill

• Anti-trigger A -- Building or pushing Docker images -> use docker-build instead
• Anti-trigger B -- Writing or modifying Helm chart templates -> use helm-chart-expert instead
• Anti-trigger C -- CI/CD pipeline configuration -> use gitlab-ci-cd instead
• Anti-trigger D -- Production deploy without an approved merge request -> stop and escalate
• Anti-trigger E -- Staging-environment operational recovery (SSH debugging, secret rotation, VM recovery) -> follow the project's environment runbooks; cluster-level pieces belong to kubernetes-deployment
• Anti-trigger F -- Promoting an image across environments (dev -> staging -> production) -> use release-promotion instead
• Anti-trigger G -- Cluster-level infrastructure ops (Minikube management, GCP firewall, tunnel debugging) -> use kubernetes-deployment instead

Required environment

• Runtime mount: .claude/skills/deployment/SKILL.md
• Tools / libraries: helm (v3+), kubectl, gcloud CLI, SSH access (for staging/production)
• Bundled resources:
  • .claude/skills/deployment/scripts/deploy-checklist.sh -- pre-deploy validation
  • .claude/skills/deployment/resources/environments.md -- environment coordinates
• Reversibility profile: hard-to-reverse -- confirm before applying to shared clusters; helm rollback can revert but causes pod disruption

Inputs

• environment: "localdev" | "<envAlias>" | "production" -- target environment (staging alias from project.json → cloud.envAlias)
• chart_path: string -- path to the Helm chart (e.g., charts/<app>/)
• values_file: string -- environment-specific values file (e.g., values.localdev.yaml)
• image_tag: string -- the image tag to deploy (git short hash or semver)

Outputs

• Format: Deploy status report inlined in agent response
• Length budget: max 30 lines for the status report; verbose pod logs or dry-run diffs go in a collapsible block
• Output template:

  Deploy: {chart} -> {environment}
  Image: {registry}/{image}:{tag}
  Helm revision: {N}
  Pod status: {count} Running, {count} other
  Health endpoint: {status code}
  Audit trail: {updated | skipped (localdev)}
  

Procedure

1. Validate prerequisites -- Confirm GCP auth (gcloud auth print-access-token), kubectl cluster access (kubectl get nodes), and image existence in registry (gcloud artifacts docker images describe $IMAGE_REGISTRY/$IMAGE:$TAG). Use $IMAGE_REGISTRY environment variable for the registry URL (do not hardcode GCP project IDs). Checkpoint: All three checks pass. If any fails, stop and report which prerequisite is missing.

2. Run pre-deploy checklist -- Execute .claude/skills/deployment/scripts/deploy-checklist.sh <image-name> <image-tag> <chart-path> to validate chart lint, template render, and image availability. Checkpoint: Script exits 0.

3. Dry-run first -- Always run helm upgrade --install --dry-run (or the chart repo's environment wrapper with its dry-run flag, if one exists) before the live deploy. Review the rendered manifests for stop conditions.

   # Local dev
   helm upgrade --install <release> charts/<app>/ -f charts/<app>/values.localdev.yaml --dry-run
   
   # Staging (<envAlias>)
   ssh <staging-host> "cd <chart-repo> && helm upgrade --install <release> charts/<app>/ -f charts/<app>/values.<envAlias>.yaml --dry-run"
   

   Checkpoint: Dry-run output reviewed. STOP if any of these appear: kind: PersistentVolumeClaim being deleted, replica count decrease >50%, resource limits removed entirely, namespace change, or kind: ServiceAccount deleted. Otherwise proceed.

4. Run helm diff -- If helm-diff plugin is available, run helm diff upgrade to see a colored diff of what will change. Checkpoint: Diff reviewed and accepted by the operator.

5. Deploy -- Execute the live deploy command. Side effect: This modifies the target Kubernetes cluster. The Helm release revision increments.

   # Local dev
   helm upgrade --install <release> charts/<app>/ -f charts/<app>/values.localdev.yaml
   
   # Staging (<envAlias>)
   ssh <staging-host> "cd <chart-repo> && helm upgrade --install <release> charts/<app>/ -f charts/<app>/values.<envAlias>.yaml"
   

   Checkpoint: helm history shows the new revision with status deployed.

Environments Reference

Environment	Infra	Namespace	Access
localdev	Minikube	<app-namespace>	*.<localdev-host> via /etc/hosts
<envAlias> (staging)	Cloud VM + Minikube	<app-namespace>	SSH tunnel
production	Edge device + k3s (or managed cluster)	<app-namespace>	Direct

Service Ports (localdev)

Service	Domain	Port
Web portal	<localdev-host>	80
Device N	dN.<localdev-host>	80
Keycloak	keycloak.<localdev-host>	80
PgAdmin	pgadmin.<localdev-host>	80

Self-check before returning

• Every file cited has been read; no claim references an unopened file.
• Output matches the format above.
• Uncertain claims tagged [LOW-CONFIDENCE].
• No hardcoded paths or environment-specific values leaked.
• Pre-deploy checklist script was run and exited 0.
• helm upgrade --dry-run was executed before the live deploy.
• No NEXT_PUBLIC_* variables were passed as --build-arg (build-time bake violates 12-factor; use window.__ENV__ runtime bridge).
• Registry URL used $IMAGE_REGISTRY variable, not a hardcoded GCP project ID.
• All pods in target namespace are Running.
• Health endpoint returned HTTP 200.
• Version-pinning audit trail was updated (staging/production only, if the project uses one).
• No --push command was run without the operator understanding it writes to the shared registry.

Common mistakes to avoid

• DO NOT use NEXT_PUBLIC_* as Docker --build-arg -- this bakes environment-specific values into the image, violating 12-factor build-once/deploy-anywhere. Use the window.__ENV__ runtime bridge pattern instead (server renders <script>window.__ENV__={...}</script>, client reads from window.__ENV__).
• DO NOT hardcode GCP project IDs in commands -- use the $IMAGE_REGISTRY variable.
• DO NOT run the live deploy before the dry-run -- always --dry-run first.
• DO NOT skip helm dependency update after modifying subchart Chart.yaml versions.
• DO NOT run --push to the shared registry without confirming the intended tag -- pushes are not easily reversible.
• DO NOT deploy to production without an approved merge request.
• DO NOT use latest tag in any environment.
• DO NOT confuse this skill with release-promotion -- this skill deploys to one environment; release-promotion manages the digest handoff across environments.

Escalation

• Stop and ask when: Target is production and there is no approved MR.
• Stop and ask when: Dry-run shows any stop condition (PVC deletion, replica decrease >50%, resource limits removed, namespace change).
• Stop and ask when: Post-deploy verification fails after 2 retry cycles (pods not Running, health endpoint not responding).
• Stop and ask when: The image tag does not exist in the registry.
• Refuse and explain when: Asked to deploy to production without confirmed approved MR URL. Required: operator must provide the MR URL before the skill proceeds with production deploy commands.

Deploy the web portal to localdev after a new feature merge Step 1: Validate prerequisites gcloud auth print-access-token > /dev/null 2>&1 # Auth valid kubectl get nodes # Cluster accessible

Step 2: Pre-deploy checklist .claude/skills/deployment/scripts/deploy-checklist.sh abc1234 charts//

Step 3: Dry-run helm upgrade --install charts// -f charts//values.localdev.yaml --dry-run

Reviewed: no PVC deletions, no replica decreases, no namespace changes.

Step 4: Deploy helm upgrade --install charts// -f charts//values.localdev.yaml

Step 5: Verify kubectl get pods -n

NAME READY STATUS RESTARTS

--7b9f8c6d4-x2k9m 1/1 Running 0

curl http:///api/health

{"status":"ok"}

</procedure_trace> Deploy: -> localdev Image: $IMAGE_REGISTRY/:abc1234 Helm revision: 12 Pod status: 1 Running Health endpoint: 200 OK Audit trail: skipped (localdev)

Failure modes

• Mode: ImagePullBackOff -- symptom: pod stuck in ImagePullBackOff -- detection: kubectl describe pod shows auth error -- action: re-authenticate with gcloud auth login && gcloud auth configure-docker <region>-docker.pkg.dev, then regenerate the registry pull secret via the chart repo's docker-secret helper script
• Mode: Stale subchart -- symptom: Helm chart changes not applied after deploy -- detection: helm template output does not include expected changes -- action: bump version in subchart Chart.yaml, bump dependency version in parent Chart.yaml, run helm dependency update charts/<app>/
• Mode: CrashLoopBackOff -- symptom: pod restarts repeatedly -- detection: kubectl logs -n <ns> <pod> --previous shows error -- action: check for missing env vars in values.yaml, wrong image tag, or failing health probe
• Mode: Rollback needed -- symptom: deploy succeeded but application is broken -- detection: health endpoint returns non-200 or telemetry not flowing -- action: helm rollback <release> <revision> -n <namespace>, then update the version-pinning repo (if the project uses one)

Related skills

• docker-build -- defer to docker-build for image creation; deployment consumes the built image
• helm-chart-expert -- defer to helm-chart-expert for chart template modifications; compose when a deploy failure traces to a template bug
• gitlab-ci-cd -- defer to gitlab-ci-cd for pipeline configuration; deployment is the runtime execution
• release-promotion -- defer to release-promotion for cross-environment digest promotion; deployment handles the single-environment Helm upgrade that release-promotion orchestrates
• kubernetes-deployment -- defer to kubernetes-deployment for cluster-level infrastructure (Minikube management, firewall rules, tunnel debugging)

How to use

What it does

This skill runs one Helm deploy against one Kubernetes cluster that already exists, then proves the deploy worked. It walks you through prerequisite checks, a mandatory dry-run, the live helm upgrade --install, pod and health-endpoint verification, and the audit-trail update for shared environments. You end up with a short status report instead of a pile of raw kubectl output.

When to use it

• You want to ship a built image to local dev, staging, or production and confirm it came up healthy.
• A deploy already happened and you need post-deploy verification: pod health, health endpoint, ingress routes.
• A release went bad in one environment and you need helm rollback plus the follow-up audit update.
• You want to read the current state of a release — helm list, helm history, pod status.

When not to use it

• Building or pushing the image itself — use the docker-build skill.
• Editing chart templates or values structure — use the helm-chart-expert skill.
• Moving an image digest across environments — use the release-promotion skill.
• Cluster-level work such as Minikube lifecycle, firewall rules, or tunnels — use the kubernetes-deployment skill.

How to invoke

Skill(skill: "infra-pack:deployment")

Invoke it, then say which environment, chart, values file, and image tag you are deploying.

Inputs

• environment — localdev, your staging alias, or production — required.
• chart_path — path to the Helm chart, e.g. charts/<app>/ — required.
• values_file — the environment values file, e.g. values.localdev.yaml — required.
• image_tag — a git short hash or semver; never latest — required.

What you get back

A status report of at most 30 lines in the reply: chart and target environment, the deployed image reference, the new Helm revision, pod counts by state, the health-endpoint status code, and whether the audit trail was updated or skipped. Verbose logs and dry-run diffs stay in a collapsible block. Side effects are real: the cluster changes and the Helm revision increments.

Worked example

Skill(skill: "infra-pack:deployment")
Deploy the web portal to localdev at image tag abc1234, chart charts/<app>/.

→ auth + cluster + registry checks pass
→ pre-deploy checklist script exits 0
→ helm upgrade --dry-run reviewed: no PVC deletion, no replica drop
→ helm upgrade --install runs; history shows revision 12 deployed
→ 1/1 pod Running, /api/health returns 200

Deploy: <app> -> localdev
Image: $IMAGE_REGISTRY/<main-app>:abc1234
Helm revision: 12
Pod status: 1 Running
Health endpoint: 200 OK
Audit trail: skipped (localdev)

Related

• docker-build — build and push the image before you deploy it.
• helm-chart-expert — change chart templates when a deploy failure traces to one.
• release-promotion — promote a digest from one environment to the next.
• kubernetes-deployment — cluster-level infrastructure rather than a single release.