| name | bump-port-agent |
| description | Bump port-agent Helm chart appVersion and image tag to match port-labs/port-agent GitHub releases. Lists releases, diffs against Chart.yaml appVersion, compares app/core/config.py Settings to values.yaml, detects stale helm env keys, classifies breaking vs notable changes, asks approval before edit. Use when user says bump port-agent, update port-agent version, sync helm chart with port-agent release, dry run port-agent bump, or upgrade appVersion. |
Bump port-agent (helm + image)
Files
| File | What |
|---|
charts/port-agent/Chart.yaml | version (chart), appVersion (app image tag) |
charts/port-agent/values.yaml | env.normal, env.secret defaults |
charts/port-agent/README.md | install examples + config table |
Image: ghcr.io/port-labs/port-agent — tag from appVersion when image.tag empty.
Workflow
Copy checklist, track progress:
- [ ] 1. Read current versions
- [ ] 2. List GH releases + pick target
- [ ] 3. Diff releases + classify breaking / notable
- [ ] 4. Diff config.py + env/docs drift + stale helm keys
- [ ] 5. Report (dry run stops here)
- [ ] 6. Apply bump (after explicit yes)
1. Current versions
grep -E '^(version|appVersion):' charts/port-agent/Chart.yaml
Normalize tags for compare: ensure v prefix (0.8.9 → v0.8.9). CURRENT / TARGET must match GH release tags.
2. List releases
gh release list --repo port-labs/port-agent --limit 15
- Target = user-named tag, else Latest
- Already on target? Tell user. Stop unless they want chart-only bump.
3. Diff app releases
gh release view "$TARGET" --repo port-labs/port-agent
gh api "repos/port-labs/port-agent/compare/${CURRENT}...${TARGET}" \
--jq '.commits[].commit.message'
gh api "repos/port-labs/port-agent/compare/${CURRENT}...${TARGET}" \
--jq '.files[] | "\(.status)\t\(.filename)"'
Read full release body too (gh release view).
If chart more than one release behind TARGET, skim intermediate release notes too.
Classify findings into three tiers (report all three in step 5):
| Tier | Examples | Blocks bump? |
|---|
| Breaking | Major semver; BREAKING/removed/deprecated in notes; Settings field removed/renamed; new required field (no default) | Yes — need explicit yes |
| Notable | Logging/sanitization/output changes; default behavior shift with same env keys; new optional Settings field operators may want | No — inform user; README optional |
| Internal | Tests, CI, refactors, Dockerfile-only | No — skip unless user cares |
Breaking signals:
| Signal | Action |
|---|
Major semver (v1.x → v2.x) | Breaking |
| "breaking", "BREAKING", "removed", "deprecated" in release/commits | Breaking |
Settings field removed or renamed (config.py diff) | Breaking + list |
New required Settings field (no default in pydantic model) | Breaking + list |
| Helm env key maps to removed/renamed upstream field | Breaking + list |
Notable signals (do not block; mention in report):
| Signal | Action |
|---|
Log format, redaction, verbosity (DETAILED_LOGGING, new logging.py, etc.) | Notable |
| Webhook/invoker/streamer behavior change, same env contract | Notable |
New optional Settings field not yet in chart (LOG_LEVEL, POLLING_*, …) | Notable — add to helm only if Port docs say operators need it |
4. Env + docs drift
4a. Mandatory — app/core/config.py
Always fetch and diff. Do not skip when compare file list omits config.py.
CONFIG_PATH="app/core/config.py"
gh api "repos/port-labs/port-agent/contents/${CONFIG_PATH}?ref=${CURRENT}" --jq '.content' | base64 -d > /tmp/port-agent-config-current.py
gh api "repos/port-labs/port-agent/contents/${CONFIG_PATH}?ref=${TARGET}" --jq '.content' | base64 -d > /tmp/port-agent-config-target.py
diff -u /tmp/port-agent-config-current.py /tmp/port-agent-config-target.py
Parse class Settings(BaseSettings) fields at CURRENT and TARGET. This is upstream env schema.
Also scan compare changed files under app/**, README.md, streamers — for logic tied to existing env keys.
4b. Helm env keys
grep -E '^\s+[A-Z][A-Z0-9_]*:' charts/port-agent/values.yaml
Build two sets:
helm_env — keys under env.normal + env.secretsettings_fields — field names from Settings in config.py at TARGET
4c. Stale helm env detection
| Check | Condition | Action |
|---|
| Stale helm key | In helm_env but not in settings_fields at TARGET | Warn: likely dead config (e.g. legacy GITLAB_URL). Propose remove from values.yaml + README only with user approval — not auto on routine bump |
| App-only field | In settings_fields but not in helm_env | Info only. Flag if new in this release or Port docs require operator config; else skip (many internal defaults exist) |
| Release delta | Field added/removed/renamed in config.py diff | Drive breaking/notable tier + helm/README updates |
gh api "search/code?q=${KEY}+repo:port-labs/port-agent" --jq '.total_count'
4d. Docs checklist
Do not bump values.yaml for unrelated chart-only tweaks or to expose every Settings field.
5. Report + approval
Show user:
CURRENT → TARGET- Release summary (
gh release view)
- Breaking (or none)
- Notable (or none)
- Stale helm keys (or none)
- Proposed edits:
Chart.yaml: appVersion: "<TARGET>", version: patch +1values.yaml / README.md only if drift or approved stale-key cleanup
- Commits not made unless user asked
If there are any breaking changes -- Ask: "Proceed with bump?" — required before step 6. On breaking items, call them out explicitly.
6. Apply (after yes only)
version: 0.8.15
appVersion: "v0.8.10"
Commit message style (repo norm):
chore(port-agent): bump chart version to X.Y.Z and update app version to vA.B.C
Optional body: README/env changes one line.
Verify:
grep -E '^(version|appVersion):' charts/port-agent/Chart.yaml
helm template test charts/port-agent --set env.normal.PORT_ORG_ID=test 2>&1 | head -5
Quick commands
APP=$(grep '^appVersion:' charts/port-agent/Chart.yaml | awk '{print $2}' | tr -d '"')
gh release list --repo port-labs/port-agent --limit 5
echo "chart appVersion: $APP"
Boundaries
- Stale key removal = separate decision — never silent delete on routine bump
gh need auth; fail → tell user login (gh auth status)- Chart
version ≠ app appVersion; both update on app bump
