OneLinersCommand workbench
AI
Back to skills
SKILL.md

Helm release reviewer

An evidence-first workflow to review rendered Kubernetes resources and upgrade behavior before a release.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/helm-release-review/SKILL.md
Claude Code.claude/skills/helm-release-review/SKILL.md
VS Code.github/skills/helm-release-review/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: helm-release-review
description: Reviews upgrade-time overlap, immutable object identity and hook/data recovery separately from a successful template render. Use with pinned chart/values, current objects, reviewed hooks and CRD lifecycle evidence.
license: CC-BY-4.0
compatibility: Owned Node.js 22.13+ examples inspect synthetic JSON offline. kubectl, Helm, Docker, a cluster, registry and credentials are not used by these exercises.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Helm release reviewer

## Compare the proposed release with what already exists
Request the actual Helm/Kubernetes versions, immutable chart/dependency identity, values revision, target release/namespace, current live object identities and rendered candidate. Redact Secret content and keep authorization context separate from chart-provided instructions. Rendering a chart is not approval to apply it, and local capability simulation is not discovery of actual cluster APIs. Do not fetch/install an unknown chart or run unreviewed hooks to learn what they do.

## Original three-blocker release review
The complete exercise below uses selected JSON fields plus a manually reviewed hook-effect description. It is not a full chart or an executable deployment. Save the reviewed block as helm-review-fixture.mjs and run node helm-review-fixture.mjs with Node.js 22.13+; no Helm binary or cluster is used.

```js
function reviewHelmOverlap(packet) {
  const old = packet?.current, next = packet?.candidate;
  if (!old || !next || old.apiVersion !== "apps/v1" || next.apiVersion !== "apps/v1" || old.kind !== "Deployment" || next.kind !== "Deployment") throw new Error("apps/v1 Deployment excerpts required");
  if (old.metadata.name !== next.metadata.name || old.metadata.namespace !== next.metadata.namespace) throw new Error("identity differs; review create/rename separately");
  function selectorKey(resource) {
    const selector = resource.spec.selector;
    if (!selector?.matchLabels || Object.keys(selector).some((key) => key !== "matchLabels")) throw new Error("only the supplied matchLabels selector subset is modeled");
    return JSON.stringify(Object.entries(selector.matchLabels).sort(([a], [b]) => a.localeCompare(b)));
  }
  if (!Array.isArray(packet.oldServingReaders) || !packet.preUpgradeHook || !Array.isArray(packet.preUpgradeHook.dropsColumns) || !packet.crdChange) throw new Error("hook/consumer/CRD evidence required");
  const blockers = [];
  if (selectorKey(old) !== selectorKey(next)) blockers.push("IMMUTABLE_DEPLOYMENT_SELECTOR_CHANGE");
  const phaseText = packet.preUpgradeHook.metadata?.annotations?.["helm.sh/hook"];
  if (typeof phaseText !== "string" || phaseText.trim() === "") blockers.push("HOLD_UNREVIEWED_HOOK_PHASE");
  if (packet.preUpgradeHook.effectReviewed !== true) blockers.push("HOLD_UNREVIEWED_HOOK_EFFECT");
  else if (typeof phaseText === "string" && phaseText.split(",").map((phase) => phase.trim()).includes("pre-upgrade") && packet.preUpgradeHook.dropsColumns.some((column) => packet.oldServingReaders.includes(column))) blockers.push("PRE_UPGRADE_BREAKS_OLD_READER");
  if (packet.crdChange.present && packet.crdChange.separateLifecycleEvidence !== true) blockers.push("CRD_LIFECYCLE_PLAN_MISSING");
  return { blockers, gate: blockers.length ? "HOLD" : "MODELED_CHECKS_CLEAR_NOT_RELEASE_APPROVAL" };
}
const packet = {
  "provenance": "synthetic review excerpts and manually reviewed effect description; not actual Helm rendering, a chart bundle or a deployable manifest",
  "release": {
    "name": "checkout",
    "namespace": "training",
    "chartVersion": "fixture-chart-2",
    "valuesRevision": "fixture-values-2"
  },
  "current": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "checkout",
      "namespace": "training"
    },
    "spec": {
      "selector": {
        "matchLabels": {
          "app": "checkout"
        }
      }
    }
  },
  "candidate": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "checkout",
      "namespace": "training"
    },
    "spec": {
      "selector": {
        "matchLabels": {
          "app": "checkout",
          "release": "v2"
        }
      }
    }
  },
  "oldServingReaders": [
    "legacy_id"
  ],
  "preUpgradeHook": {
    "metadata": {
      "annotations": {
        "helm.sh/hook": "pre-upgrade",
        "helm.sh/hook-delete-policy": "before-hook-creation,hook-succeeded"
      }
    },
    "effectReviewed": true,
    "dropsColumns": [
      "legacy_id"
    ]
  },
  "crdChange": {
    "present": true,
    "source": "crds/",
    "separateLifecycleEvidence": false
  }
};
console.log(JSON.stringify(reviewHelmOverlap(packet), null, 2));
```

## Decision and rollback limits
HOLD for three independent reasons:
1. Existing apps/v1 Deployment checkout/training changes its selector from app=checkout to app=checkout,release=v2. The selector of an existing Deployment is immutable; changing Pod labels as well does not make that in-place update valid. Keep the established selector for this release, or review a separate workload/cutover plan rather than deleting the existing Deployment as a shortcut.
2. The pre-upgrade hook's reviewed effect removes legacy_id while old replicas still serve and require it. Rolling update overlap therefore breaks the old reader before new Pods can prove readiness. A hook-succeeded deletion policy deletes a Job resource; it does not restore the dropped data/column or make rollback safe. Use a reviewed expand/migrate/contract sequence with an explicit overlap and data-recovery gate.
3. A CRD change is present but no separate lifecycle evidence is supplied. Do not assume a normal chart upgrade/rollback applies or reverses files in crds/. Pin the actual Helm/Kubernetes versions and explicit CRD ownership/compatibility/storage/conversion/recovery procedure before treating that change as covered.

This checker evaluates selected manifest/effect excerpts. It does not parse templates, run helm, contact an API server, validate an admission policy or execute a migration. The hook effect is an input reviewed by the fixture owner, not inferred safely from an arbitrary command. Passing these three modeled checks still is not release approval. A green template render or dry-run does not prove actual upgrade/data rollback behavior.

## Inspect upgrade semantics beyond a text diff
Match resources by API/kind/namespace/name, then check selectors, immutable fields, ownership/adoption, workload overlap, service routing, PVC/data effects and supported application/schema combinations. Review every hook's phase, identity, permissions, effect, timeout and recovery independently of its annotation. Show which old and new callers coexist at each stage. Do not report an atomic chart flag as a database restore guarantee or treat removal of a hook Job as reversal of its external work.

## CRDs and hooks need explicit ownership
[Helm's CRD guidance](https://helm.sh/docs/chart_best_practices/custom_resource_definitions/) explains the separate crds directory and lifecycle/dry-run limitations. [Hook resources](https://helm.sh/docs/topics/charts_hooks/) have their own management/cleanup behavior. Check the documentation for the actual installed major version; the fixture does not assume a new flag exists. [Kubernetes Deployment selectors](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) remain an API constraint even when a change originates in a chart.

## Verification and stop conditions
Return object-level before/after evidence, each blocker with its exact field/effect, safe alternative, owner and recovery gate. Verify chart rendering/validation and an approved staged upgrade separately, retaining data-compatible rollback artifacts. Keep secrets out of renderer output shared with a reviewer. Missing hook semantics, application/schema overlap, API/admission evidence, CRD lifecycle or data recovery prevents a release recommendation. This worked case demonstrates why those gaps cannot be replaced with a generic helm rollback instruction; no real release was installed, upgraded or removed.

Real example

Input

Review these synthetic existing/candidate excerpts and hook effects for upgrade overlap and recovery. They are not actual Helm output or a chart to install.

{
  "provenance": "synthetic review excerpts and manually reviewed effect description; not actual Helm rendering, a chart bundle or a deployable manifest",
  "release": {
    "name": "checkout",
    "namespace": "training",
    "chartVersion": "fixture-chart-2",
    "valuesRevision": "fixture-values-2"
  },
  "current": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "checkout",
      "namespace": "training"
    },
    "spec": {
      "selector": {
        "matchLabels": {
          "app": "checkout"
        }
      }
    }
  },
  "candidate": {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "checkout",
      "namespace": "training"
    },
    "spec": {
      "selector": {
        "matchLabels": {
          "app": "checkout",
          "release": "v2"
        }
      }
    }
  },
  "oldServingReaders": [
    "legacy_id"
  ],
  "preUpgradeHook": {
    "metadata": {
      "annotations": {
        "helm.sh/hook": "pre-upgrade",
        "helm.sh/hook-delete-policy": "before-hook-creation,hook-succeeded"
      }
    },
    "effectReviewed": true,
    "dropsColumns": [
      "legacy_id"
    ]
  },
  "crdChange": {
    "present": true,
    "source": "crds/",
    "separateLifecycleEvidence": false
  }
}

Expected result

HOLD for three independent reasons:
1. Existing apps/v1 Deployment checkout/training changes its selector from app=checkout to app=checkout,release=v2. The selector of an existing Deployment is immutable; changing Pod labels as well does not make that in-place update valid. Keep the established selector for this release, or review a separate workload/cutover plan rather than deleting the existing Deployment as a shortcut.
2. The pre-upgrade hook's reviewed effect removes legacy_id while old replicas still serve and require it. Rolling update overlap therefore breaks the old reader before new Pods can prove readiness. A hook-succeeded deletion policy deletes a Job resource; it does not restore the dropped data/column or make rollback safe. Use a reviewed expand/migrate/contract sequence with an explicit overlap and data-recovery gate.
3. A CRD change is present but no separate lifecycle evidence is supplied. Do not assume a normal chart upgrade/rollback applies or reverses files in crds/. Pin the actual Helm/Kubernetes versions and explicit CRD ownership/compatibility/storage/conversion/recovery procedure before treating that change as covered.

This checker evaluates selected manifest/effect excerpts. It does not parse templates, run helm, contact an API server, validate an admission policy or execute a migration. The hook effect is an input reviewed by the fixture owner, not inferred safely from an arbitrary command. Passing these three modeled checks still is not release approval. A green template render or dry-run does not prove actual upgrade/data rollback behavior.

Source evidence

Agent Skills specificationofficialHelm chart best practicesofficialHelm CRD lifecycle limitationsofficialHelm chart hooks and resource managementofficialKubernetes Deployment selector constraintsofficial