Skill — `bump-chart-version`

Layer: Layer 1 — agent generates diff and opens PR; platform team reviews; per-cluster Sync is the deploy. Scope: updating helm-templates/<chart>/Chart.yaml dependencies[].version and refreshing Chart.lock.

This skill is the agent-callable form of docs/platform/procedures/update-chart-version.md.

When to use

Triggers like:

"Bump <chart> from <old> to <new>."
"Upgrade argo-cd to 7.8.0."
"Apply CVE patch to <chart> — bump to ."

Do not use this skill for:

Major-version bumps with breaking template changes (use blue-green-chart-migration procedure).
Forking a chart (use fork-upstream-chart procedure).
Bumping a chart's local version when it's already a fork (the version: field at the top of Chart.yaml, not dependencies[].version).

Input

Required:

chart:        <chart-name>          # must exist in helm-templates/
old_version:  <semver>              # current dependencies[].version
new_version:  <semver>              # target

Optional:

representative_cluster: <cluster-folder>   # for the test render; if omitted, skill picks one
sample_helm_diff:       <bool>             # if true, run helm diff against a live cluster (requires kube context)

Steps (deterministic)

Pre-conditions.

ls helm-templates/<chart>/Chart.yaml
yq e '.dependencies[0].version' helm-templates/<chart>/Chart.yaml   # confirm == <old_version>

Read the changelog. Output a one-line note with the changelog URL or an explicit "READ THE CHANGELOG: " message. The skill does not auto-fetch; the user must confirm they've read it. If the user hasn't, stop.

Update Chart.yaml.

sed -i.bak "s/^    version: <old_version>$/    version: <new_version>/" \
  helm-templates/<chart>/Chart.yaml
rm helm-templates/<chart>/Chart.yaml.bak

(Or use yq with a path expression — depending on dependencies[] shape.)

Refresh Chart.lock.
```
helm dependency update helm-templates/<chart>
```
On failure: surface the error and stop. Common causes: new version doesn't exist, repo URL changed, network issue.

Render against the representative cluster.

sibling=${representative_cluster:-$(find helm-overrides -maxdepth 2 -type d -name '<chart>' \
                                    | grep -v '^helm-overrides/db-' | head -1)}
helm template <chart> helm-templates/<chart> -f "$sibling/custom-values.yaml" > /tmp/render.yaml

On failure: surface the error and roll back (git checkout helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock); stop and report. The bump is incompatible with current values.

(If sample_helm_diff: true)

helm diff upgrade <release> helm-templates/<chart> \
  -f helm-overrides/<sibling>/<chart>/custom-values.yaml \
  --kube-context=<context>

Capture the diff and put it in the PR body.

Open the PR.

git checkout -b chart-bump/<chart>-<new_version>
git add helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock
git add helm-templates/<chart>/charts/   # if subchart .tgz refreshed
git commit -m "chart bump: <chart> <old_version> -> <new_version>"
git push origin chart-bump/<chart>-<new_version>
gh pr create --base main --title "chart bump: <chart> <old_version> -> <new_version>"

PR body (heredoc):

## Summary
Bumps `<chart>` from `<old_version>` to `<new_version>`.

- Upstream changelog: <url>
- Procedure: `docs/platform/procedures/update-chart-version.md`
- Skill: `skills/infra/bump-chart-version.md`

## Affected clusters
<list from `grep -rl '<chart>' helm-overrides | sort -u`>

## Validation
- `helm dependency update` succeeded
- Render against `<representative_cluster>`'s overrides: clean
- (if sample_helm_diff) diff against live: <one-line summary>

## Approver
Platform team

## CMR
<ticket if applicable>

Output

A PR diff with:

helm-templates/<chart>/Chart.yaml updated (version line)
helm-templates/<chart>/Chart.lock refreshed
helm-templates/<chart>/charts/*.tgz (if the subchart was re-pulled)

The skill does not:

Sync any cluster (manual per-cluster Sync after merge).
Update any helm-overrides/<cluster>/<app>/custom-values.yaml to handle a values-shape change. If the bump requires that, stop and surface a follow-up task — don't bundle.
Open per-cluster Sync recommendations as separate work items.

Gotchas

Chart.yaml without Chart.lock is a no-op. Argo CD reads the lockfile.
The skill must roll back on render failure. Otherwise a half-committed bump leaves the repo in a broken state.
For wrapper charts whose dependencies[] has multiple entries, the skill must operate on the right one. Don't bump the wrong dep.
Major-version bumps are not this skill's job. If new_version is a major increment (7.x → 8.x), refuse and recommend blue-green-chart-migration.

Layer constraint

Layer 1. Open the PR; do not merge it; do not click Sync on any cluster.

Procedure: update-chart-version.md.
Procedure: blue-green-chart-migration.md.
ADR: ADR-A1-cache-vs-upstream-charts.md.

5.6 KiB Raw Blame History

Skill — bump-chart-version