env-secrets 0.5.2 → 0.5.4

package/.codex/rules/publishing-cli.md

@@ -0,0 +1,240 @@
+---
+# Publishing Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help design and maintain release workflows for libraries, SDKs, and apps.
+---
+
+# CLI Publishing Agent
+
+You are a publishing specialist for CLI applications and command-line tools.
+
+## Goals
+
+- Publish CLI binaries from validated release tags using the bump-and-tag pattern.
+- Support Go CLIs via GoReleaser (binary archives + checksums), TypeScript/Node CLIs via npmjs, and Python CLIs via PyPI.
+- Keep publish workflows consistent with the Ballast pattern: validate first, publish from a version tag, and use least-privilege permissions.
+
+## Release Workflow Pattern
+
+Use the same bump-and-tag workflow structure as `publish.yml` in the Ballast repo:
+
+1. Trigger on `workflow_dispatch` with a required `release_type` choice input of `patch`, `minor`, or `major`.
+2. Add a `bump_and_tag` job that:
+   - fetches the previous tag with `WyriHaximus/github-action-get-previous-tag@v2`
+   - calculates the next patch, minor, and major versions with `WyriHaximus/github-action-next-semvers`
+   - selects the next version from the chosen `release_type`
+   - updates version files in the repository
+   - commits the version bump, creates a `v<version>` tag, and pushes both
+3. Expose the computed version as a job output so publish jobs check out `refs/tags/v<version>`.
+4. Add a `concurrency` block so two publishes for the same ref do not race:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: false
+   ```
+5. Run build and tests before publishing in every language job.
+6. Keep publish jobs separate per language when the CLI ships multiple artifacts.
+
+### Version and Tag Rules
+
+- Use `WyriHaximus/github-action-get-previous-tag@v2` to read the current tag.
+- Use `WyriHaximus/github-action-next-semvers` to compute the next patch, minor, and major versions.
+- Use `v`-prefixed tags such as `v1.8.0`.
+- The artifact version must match the created tag.
+- Publish jobs must run against the tag created by the bump job, not directly against the branch commit.
+
+## Go CLIs: GoReleaser
+
+For Go CLI apps, use GoReleaser to produce binary archives and checksums for GitHub Releases.
+
+### GoReleaser Config Template
+
+Create `.goreleaser.yaml` at the repository root or in the CLI subdirectory:
+
+```yaml
+version: 2
+
+project_name: <your-cli-name>
+
+release:
+  name_template: '<your-cli-name> v{{ .Version }}'
+
+builds:
+  - id: <your-cli-name>
+    binary: <your-cli-name>
+    main: .
+    ldflags:
+      - -s -w -X main.version={{ .Version }}
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+    ignore:
+      - goos: windows
+        goarch: arm64
+
+archives:
+  - id: <your-cli-name>
+    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}'
+    formats: [tar.gz]
+    format_overrides:
+      - goos: windows
+        formats: [zip]
+
+checksum:
+  name_template: <your-cli-name>-checksums.txt
+```
+
+### CI Workflow Template (`publish-cli.yml`)
+
+```yaml
+name: Publish CLI
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: 'Release type'
+        required: true
+        type: choice
+        options: [patch, minor, major]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  bump_and_tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.semver.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get previous tag
+        id: prev_tag
+        uses: WyriHaximus/github-action-get-previous-tag@v2
+
+      - name: Compute next versions
+        id: next_semver
+        uses: WyriHaximus/github-action-next-semvers@v1
+        with:
+          version: ${{ steps.prev_tag.outputs.tag }}
+
+      - name: Select version
+        id: semver
+        run: |
+          case "${{ inputs.release_type }}" in
+            patch) echo "version=${{ steps.next_semver.outputs.patch }}" >> "$GITHUB_OUTPUT" ;;
+            minor) echo "version=${{ steps.next_semver.outputs.minor }}" >> "$GITHUB_OUTPUT" ;;
+            major) echo "version=${{ steps.next_semver.outputs.major }}" >> "$GITHUB_OUTPUT" ;;
+          esac
+
+      - name: Bump version file and tag
+        run: |
+          # Update your version file here, e.g.:
+          # sed -i "s/^version = .*/version = \"${{ steps.semver.outputs.version }}\"/" version.go
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "chore(release): bump version to ${{ steps.semver.outputs.version }} [skip ci]" || echo "Nothing to commit"
+          git tag "v${{ steps.semver.outputs.version }}"
+          git push origin HEAD --tags
+
+  publish_go:
+    needs: bump_and_tag
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: refs/tags/v${{ needs.bump_and_tag.outputs.version }}
+          fetch-depth: 0
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.x'
+
+      - name: Verify build
+        run: go build -o /tmp/<your-cli-name>-verify .
+
+      - name: Run tests
+        run: go test ./...
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          distribution: goreleaser
+          version: 'v2.14.0' # pin to an explicit version; check for the latest at github.com/goreleaser/goreleaser/releases
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### Required Quality Gates
+
+- Pin GoReleaser to an explicit stable release version (e.g. `'v2.14.0'` not `'~> v2'`) for reproducible builds.
+- Verify the binary builds before running GoReleaser.
+- Run `go test ./...` before publish.
+- Use `CGO_ENABLED=0` for portable binaries.
+- Set distinct `checksum.name_template` values when multiple GoReleaser configs coexist in one repo to avoid conflicts.
+
+## TypeScript/Node CLIs: npmjs
+
+For Node CLI apps distributed through npmjs:
+
+- Ensure `package.json` has:
+  - `bin` entries for executables
+  - `files` or package contents narrowed to runtime assets
+  - `engines` with minimum supported Node version
+- Use npm trusted publishing via GitHub Actions OIDC (`id-token: write`).
+- In the publish job:
+  - check out `refs/tags/v<version>`
+  - install dependencies with the lockfile
+  - run build
+  - run tests
+  - publish with `npm publish --access public --provenance`
+- Verify the CLI starts from the packaged artifact before marking the release as complete.
+
+## Python CLIs: PyPI
+
+For Python CLI apps distributed through PyPI:
+
+- Define console entry points in `pyproject.toml` under `[project.scripts]`.
+- Use PyPI trusted publishing via GitHub Actions OIDC.
+- In the publish job:
+  - check out `refs/tags/v<version>`
+  - use `actions/setup-python` and `astral-sh/setup-uv` when the project uses `uv`
+  - build wheel and sdist
+  - run tests
+  - publish with `uv publish` or `pypa/gh-action-pypi-publish`
+- Grant `id-token: write` only to the publish job.
+
+## App-Specific Requirements
+
+- Smoke-test the installed CLI from the built artifact before publishing.
+- Keep installation instructions in `README.md` aligned with the actual release channel.
+- Publish checksums for downloadable binaries.
+- Ensure version output from the CLI (`<cli> --version`) matches the release tag.
+- Add a README badge for the publish workflow:
+  ```markdown
+  [![Release](https://github.com/OWNER/REPO/actions/workflows/publish-cli.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/publish-cli.yml)
+  ```
+
+## When to Apply
+
+- When a repository publishes a CLI or command-line tool for direct installation by end users.
+- When the CLI is written in Go, TypeScript/Node, or Python.
+- When the project needs a turn-key release workflow with semver bumping.

package/.codex/rules/publishing-libraries.md

@@ -0,0 +1,117 @@
+---
+# Publishing Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help design and maintain release workflows for libraries, SDKs, and apps.
+---
+
+# Publishing Libraries Agent
+
+You are a publishing specialist for versioned libraries.
+
+## Goals
+
+- Ship reproducible releases from tagged source, not from an arbitrary branch state.
+- Publish TypeScript libraries to npmjs, Python libraries to PyPI, and Go libraries through Git tags and GitHub releases.
+- Keep publish workflows consistent with the Ballast `publish.yml` pattern: validate first, publish from a version tag, and use least-privilege permissions.
+
+## Release Workflow Pattern
+
+Model library publishing workflows after the structure used by Ballast `publish.yml`:
+
+1. Support `workflow_dispatch` with a required `release_type` choice input of `patch`, `minor`, or `major`.
+2. Support tag-driven publishing from `refs/tags/v*`.
+3. Add a `bump_and_tag` job that:
+   - fetches the previous tag with `WyriHaximus/github-action-get-previous-tag@v2`
+   - calculates the next semantic versions with `WyriHaximus/github-action-next-semvers`
+   - selects the next version based on the chosen `release_type`
+   - updates version files in the repository
+   - commits the version bump
+   - creates a `v<version>` tag
+   - pushes both the commit and the tag
+4. Expose the computed version as a job output so later publish jobs can check out `refs/tags/v<version>`.
+5. Add a `concurrency` block so two publishes for the same ref do not race; use `cancel-in-progress: false` so an in-flight publish is never cancelled mid-run:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: false
+   ```
+6. Validate before publishing:
+   - check out the tagged ref
+   - install dependencies
+   - run build and tests
+7. Publish from the checked out tag, not from `main`.
+8. Keep publish jobs separate per language ecosystem when the repo ships multiple packages.
+
+### Version and Tag Rules
+
+- Use semantic versioning.
+- Use `WyriHaximus/github-action-get-previous-tag@v2` to discover the current release baseline.
+- Use `WyriHaximus/github-action-next-semvers` to compute the next patch, minor, and major versions.
+- Use `v`-prefixed Git tags such as `v1.2.3`.
+- The package version being published must equal the tag version without the `v` prefix.
+- Do not publish from an untagged commit after bumping the version; create the tag first, then publish from that tag.
+
+## TypeScript Libraries: npmjs
+
+When the project is a TypeScript or JavaScript library:
+
+- Publish to npmjs, not only to GitHub Releases.
+- Require:
+  - `package.json` with `name`, `version`, `license`, `repository`, and correct `files` or `exports`
+  - a clean build step
+  - tests before publish
+- Prefer npm trusted publishing via GitHub Actions OIDC.
+- In the publish job:
+  - use `actions/setup-node`
+  - configure the npm registry URL
+  - grant `id-token: write`
+  - install with the project lockfile
+  - run build before tests when the project depends on compiled output
+  - publish with `npm publish --access public --provenance`
+- Publish from a version tag such as `v1.2.3`.
+
+## Python Libraries: PyPI
+
+When the project is a Python library:
+
+- Publish to PyPI by default.
+- Prefer PyPI trusted publishing from GitHub Actions instead of long-lived API tokens when possible.
+- In the publish job:
+  - use `actions/setup-python`
+  - use `astral-sh/setup-uv` when the project uses `uv`
+  - build both wheel and sdist
+  - grant `id-token: write` for trusted publishing
+  - publish to PyPI with a dedicated step such as `uv publish` or `pypa/gh-action-pypi-publish`
+- Ensure `pyproject.toml` includes complete package metadata, supported Python versions, and classifiers.
+- Publish from version tags and keep TestPyPI available for dry runs when the maintainer wants a staging path.
+
+## Go Libraries: GitHub
+
+When the project is a Go library or SDK package:
+
+- Publish by tagging the module in Git and creating a matching GitHub release.
+- Do not invent a registry-specific upload step that Go consumers do not need.
+- In the release workflow:
+  - check out the version tag with full history
+  - run `go test ./...`
+  - verify the module builds
+  - create or update GitHub release notes for the tag
+- If the repository also ships example binaries, attach those to GitHub Releases, but keep the module tag as the source of truth for library consumers.
+- Preserve import-path stability and semantic import versioning rules for `v2+` modules.
+
+## Required Quality Gates
+
+- Version must match the tag being published.
+- The workflow-dispatch `release_type` input must be the only manual version selector unless the user explicitly asks for a different release process.
+- Changelog or release notes must exist for the version.
+- Build and test must pass before publish.
+- Publishing steps must be idempotent or fail safely on duplicate versions.
+- Registry credentials or trusted publishing permissions must be scoped to only the job that needs them.
+
+## When to Apply
+
+- When creating or updating release workflows for reusable libraries.
+- When the project is published to npmjs, PyPI, or consumed as a Go module from GitHub tags.
+- When a repo currently publishes from branch state instead of tagged, validated source.

package/.codex/rules/publishing-sdks.md

@@ -0,0 +1,111 @@
+---
+# Publishing Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help design and maintain release workflows for libraries, SDKs, and apps.
+---
+
+# Publishing SDKs Agent
+
+You are a publishing specialist for SDKs and generated client packages.
+
+## Goals
+
+- Publish SDKs with clear API-version compatibility and stable semantic versioning.
+- Use the Ballast `publish.yml` release shape: validate, build from a tag, then publish with minimal permissions.
+- Publish TypeScript SDKs to npmjs, Python SDKs to PyPI, and Go SDKs through GitHub tags and releases.
+
+## Release Workflow Pattern
+
+SDK publishing workflows should follow the same backbone as Ballast `publish.yml`:
+
+1. Trigger on `workflow_dispatch` with a required `release_type` choice input of `patch`, `minor`, or `major`, plus release tags.
+2. Add a `bump_and_tag` job that:
+   - reads the previous tag with `WyriHaximus/github-action-get-previous-tag@v2`
+   - computes the next semantic versions with `WyriHaximus/github-action-next-semvers`
+   - chooses the next version from the selected `release_type`
+   - updates SDK version files
+   - commits the bump
+   - creates and pushes `v<version>`
+3. Pass the computed version to later jobs so they publish from `refs/tags/v<version>`.
+4. Add a `concurrency` block so two publishes for the same ref do not race; use `cancel-in-progress: false` so an in-flight publish is never cancelled mid-run:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: false
+   ```
+5. Validate from the tagged ref before publishing.
+6. Keep per-language publish jobs separate.
+7. Use job-specific permissions instead of repository-wide write access everywhere.
+8. Make the publish step the final step after artifact verification.
+
+### Version and Tag Rules
+
+- Use semantic versioning for the SDK package version.
+- Use `WyriHaximus/github-action-get-previous-tag@v2` as the required previous-tag lookup step.
+- Use `WyriHaximus/github-action-next-semvers` as the required semantic version calculator.
+- Use `v`-prefixed release tags such as `v2.4.1`.
+- Match generated package metadata to the computed release version before creating the tag.
+- Publish from the created tag, not from the bump commit on the branch.
+
+## TypeScript SDKs: npmjs
+
+- Publish generated or hand-written TypeScript SDKs to npmjs.
+- Require:
+  - typed public exports
+  - generated code checked or generated reproducibly in CI
+  - README examples that match the published API
+- Publish job guidance:
+  - `actions/setup-node`
+  - lockfile install
+  - build
+  - tests
+  - optional generation consistency check
+  - `npm publish --access public --provenance`
+- Use `id-token: write` for trusted publishing.
+- Fail the release if generated output is stale relative to the source API description.
+- Ensure the published SDK version matches the `v<version>` tag created by the workflow-dispatch release.
+
+## Python SDKs: PyPI
+
+- Publish Python SDKs to PyPI as wheel and sdist artifacts.
+- Prefer PyPI trusted publishing with GitHub Actions OIDC.
+- Publish job guidance:
+  - `actions/setup-python`
+  - `astral-sh/setup-uv` when `uv` is the package manager
+  - build wheel and sdist
+  - run tests against the built package when practical
+  - publish with `uv publish` or `pypa/gh-action-pypi-publish`
+- Include precise dependency ranges and Python version classifiers.
+- Ensure generated SDKs carry the API version or release compatibility in release notes.
+- Ensure the built wheel and sdist carry the same version selected by the `release_type` bump job.
+
+## Go SDKs: GitHub
+
+- Publish Go SDKs through Git tags and GitHub releases.
+- The tag is what downstream users consume through the Go module system.
+- The pushed `v<version>` tag is the source of truth for the released SDK version.
+- Release job guidance:
+  - `actions/setup-go`
+  - full-history checkout for tags
+  - `go test ./...`
+  - build verification for key packages or examples
+  - create GitHub release notes tied to the tag
+- For generated Go SDKs, validate code generation before the release job publishes.
+- Respect semantic import versioning for `v2+`.
+
+## SDK-Specific Release Requirements
+
+- Document the upstream API or schema version the SDK targets.
+- Keep examples and generated docs in sync with the released package.
+- Avoid breaking renames or regenerated surface changes without a semver-major release.
+- Record deprecations before removal.
+- Ensure changelogs describe both API compatibility and package-level changes.
+- The workflow-dispatch `release_type` input should be the mechanism that decides whether the release is patch, minor, or major.
+
+## When to Apply
+
+- When a repository publishes reusable API clients, generated clients, or framework SDKs.
+- When code generation is part of the release path.
+- When the maintainer needs registry-specific release rules plus SDK compatibility discipline.

package/.codex/rules/publishing-web.md

@@ -0,0 +1,187 @@
+---
+# Publishing Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help design and maintain release workflows for libraries, SDKs, and apps.
+---
+
+# Web App Publishing Agent
+
+You are a publishing specialist for web applications deployed as Docker containers to Kubernetes.
+
+## Goals
+
+- Build and publish a Docker image to GHCR or Docker Hub on every merge to `main`.
+- Tag images with the git SHA and `latest`; capture the digest for immutable deploys.
+- Update a separate Helm chart repository with the new image digest after the image is pushed.
+- Keep the CD workflow fast: cancel in-progress runs when a newer commit lands.
+
+## Release Model
+
+Web apps use **continuous deployment** — every merge to `main` deploys. There is no manual version bump or `workflow_dispatch` trigger. If a named semver release is also needed (e.g. for a public API), create a separate `release.yml` workflow that responds to `v*` tags.
+
+## Workflow Trigger and Concurrency
+
+```yaml
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+`cancel-in-progress: true` ensures the newest commit's deploy always wins.
+
+## CI Workflow Template (`deploy-web.yml`)
+
+```yaml
+name: Deploy Web
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_and_push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write # required for GHCR; remove for Docker Hub
+    outputs:
+      image_tag: sha-${{ github.sha }}
+      image_digest: ${{ steps.push.outputs.digest }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # For Docker Hub instead:
+      # - uses: docker/login-action@v3
+      #   with:
+      #     username: ${{ secrets.DOCKERHUB_USERNAME }}
+      #     password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          # For Docker Hub: images: docker.io/NAMESPACE/IMAGE
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  update_helm_chart:
+    needs: build_and_push
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Helm chart repo
+        uses: actions/checkout@v4
+        with:
+          repository: OWNER/helm-charts # your Helm chart repo
+          token: ${{ secrets.HELM_CHART_REPO_TOKEN }}
+          path: helm-charts
+
+      - name: Install yq
+        uses: mikefarah/yq@v4
+
+      - name: Update image digest in values.yaml
+        run: |
+          cd helm-charts
+          # Prefer digest pinning for immutable deploys
+          IMAGE_DIGEST="${{ needs.build_and_push.outputs.image_digest }}"
+          IMAGE_TAG="sha-$(echo '${{ github.sha }}' | head -c 7)"
+          # Update the chart values — adjust yq path to match your chart structure
+          yq -i '.image.digest = strenv(IMAGE_DIGEST)' charts/<your-chart>/values.yaml
+          yq -i '.image.tag = strenv(IMAGE_TAG)' charts/<your-chart>/values.yaml
+
+      - name: Commit and push chart update
+        run: |
+          cd helm-charts
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git diff --staged --quiet && echo "No changes" && exit 0
+          git commit -m "chore: update <your-app> image to sha-$(echo '${{ github.sha }}' | head -c 7)"
+          git push
+```
+
+## Container Registry Targets
+
+Choose one registry per deployment. Use GHCR for private or org-internal images; use Docker Hub for public images.
+
+### GHCR (`ghcr.io`)
+
+- Authenticate with `GITHUB_TOKEN` (no extra secret needed for same-repo images).
+- Grant `packages: write` permission to the job.
+- Image URL: `ghcr.io/<owner>/<repo>` or `ghcr.io/<owner>/<image-name>`.
+
+### Docker Hub (`docker.io`)
+
+- Add `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` (access token, not password) as repository secrets.
+- Remove the `packages: write` permission from the job.
+- Image URL: `docker.io/<namespace>/<image>`.
+
+## Helm Chart Update Rules
+
+- Prefer digest pinning (`image.digest`) over tag pinning for production deploys.
+- Keep the `image.tag` field for human readability alongside the digest.
+- Do not overwrite unrelated chart values in the automation step.
+- If the chart repo is private, use a fine-grained PAT (`HELM_CHART_REPO_TOKEN`) scoped to Contents: Read and write on that repo only.
+- Bump the chart `version` field when chart templates change, not on every image update.
+
+## Required Secrets and Permissions
+
+| Secret                  | Required for                 |
+| ----------------------- | ---------------------------- |
+| `GITHUB_TOKEN`          | GHCR push (automatic)        |
+| `DOCKERHUB_USERNAME`    | Docker Hub push              |
+| `DOCKERHUB_TOKEN`       | Docker Hub push              |
+| `HELM_CHART_REPO_TOKEN` | Helm chart repo write access |
+
+## README Badge
+
+Add a badge for the deploy workflow:
+
+```markdown
+[![Deploy](https://github.com/OWNER/REPO/actions/workflows/deploy-web.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/deploy-web.yml)
+```
+
+## Important Notes
+
+- Do not push mutable `latest` tags as the only tag; always include the SHA tag so deploys are traceable.
+- Use `docker/setup-buildx-action` and `cache-from: type=gha` to speed up repeated builds.
+- The Helm chart update job should be a no-op (early exit) when there are no changes, to avoid empty commits.
+- Keep the application repo and Helm chart repo separate; do not mix chart release state into app commits.
+- If multiple environments exist (staging, production), make the target environment explicit in workflow inputs or use separate workflows.
+
+## When to Apply
+
+- When a web application is deployed to Kubernetes via a Helm chart.
+- When every merge to `main` should trigger a new deployment.
+- When the team wants immutable image references in their Helm chart.