graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/.github/workflows/staging.yaml

@@ -0,0 +1,450 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# On every push to main: build and push the image tagged with the SHORT commit
+# SHA (${GITHUB_SHA::7}, the same value `git rev-parse --short HEAD` gives a
+# workstation `graph-agents-cli deploy --env <env>` in argocd mode), then land
+# it in staging according to CD in .github/agent.env:
+#   argocd:    update values-staging.yaml image.tag and open a PR with auto-merge
+#              (closing older staging PRs it supersedes); Argo CD rolls it out
+#              and its health checks (the readiness probe, /ready) show whether
+#              it landed (`graph-agents-cli deploy --env staging --status`).
+#   helm-push: run `graph-agents-cli deploy --env staging --image ...` on a
+#              self-hosted runner with the kubeconfig of the `staging`
+#              environment, then verify the rollout (rollout status, /health
+#              and /ready through a port-forward), both in one kube context
+#              (environments.staging.context, else the kubeconfig's current one).
+# Pushes that only change the per-environment values files (the image tags
+# this workflow, promote-to-prod and `graph-agents-cli deploy` write in argocd
+# mode) do not start it, so a merged staging PR never triggers another build.
+# Run it by hand (workflow_dispatch, main only) to re-deploy main, e.g. after
+# changing only values-staging.yaml in helm-push mode.
+# This file is copied verbatim into the project (not rendered).
+
+name: staging
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'deployment/helm/*/values-dev.yaml'
+      - 'deployment/helm/*/values-staging.yaml'
+      - 'deployment/helm/*/values-prod.yaml'
+  workflow_dispatch:
+
+concurrency:
+  group: staging
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # A manual run from another branch would deploy that branch to staging.
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+      packages: write
+    outputs:
+      cd: ${{ steps.settings.outputs.cd }}
+      tag: ${{ steps.settings.outputs.tag }}
+      image: ${{ steps.settings.outputs.image }}
+      chart_path: ${{ steps.settings.outputs.chart_path }}
+      release: ${{ steps.settings.outputs.release }}
+      namespace: ${{ steps.settings.outputs.namespace }}
+      kube_context: ${{ steps.settings.outputs.kube_context }}
+      graph_agents_cli_spec: ${{ steps.settings.outputs.graph_agents_cli_spec }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Load project settings
+        run: |
+          # .github/agent.env is data and is never sourced: each NAME=VALUE line is
+          # checked and copied to GITHUB_ENV, so a value may hold spaces or shell
+          # metacharacters (a PEP 508 install spec, for example). Only the settings
+          # listed in `known` are accepted: any other name (BASH_ENV, SHELLOPTS, PS4,
+          # PATH, PYTHONPATH, ...) could change how later steps run. To add a setting,
+          # extend `known` in all three workflows. Comment and blank lines are skipped;
+          # blanks around the value, one pair of quotes around it and a trailing
+          # " # comment" are dropped (no escapes, no expansion). Nothing reaches
+          # GITHUB_ENV unless the whole file is valid.
+          file=.github/agent.env
+          known="IMAGE_REPOSITORY RELEASE_NAME CHART_PATH RUNTIME CD GRAPH_AGENTS_CLI_SPEC"
+          if [ ! -f "$file" ]; then
+            echo "::error file=$file::$file is missing: it holds the project settings these workflows read." >&2
+            exit 1
+          fi
+          lineno=0
+          seen=" "
+          settings=()
+          while IFS= read -r line || [ -n "$line" ]; do
+            lineno=$((lineno + 1))
+            line="${line%$'\r'}"
+            if [ "$lineno" -eq 1 ]; then
+              line="${line#$'\xef\xbb\xbf'}"
+            fi
+            if [[ "$line" =~ ^[[:space:]]*(#|$) ]]; then
+              continue
+            fi
+            if ! [[ "$line" =~ ^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)[[:space:]]*=(.*)$ ]]; then
+              echo "::error file=$file,line=$lineno::expected NAME=VALUE, got: $line" >&2
+              exit 1
+            fi
+            name="${BASH_REMATCH[1]}"
+            value="${BASH_REMATCH[2]}"
+            case " $known " in
+              *" $name "*) ;;
+              *)
+                hint=""
+                if [ "$name" = CLI_VERSION_PIN ]; then
+                  hint=" (replaced by GRAPH_AGENTS_CLI_SPEC=<install spec>)"
+                fi
+                echo "::error file=$file,line=$lineno::$name is not a setting these workflows read${hint}; known: $known." >&2
+                exit 1
+                ;;
+            esac
+            case "$seen" in
+              *" $name "*)
+                echo "::error file=$file,line=$lineno::$name is set twice." >&2
+                exit 1
+                ;;
+            esac
+            seen="$seen$name "
+            value="${value#"${value%%[![:space:]]*}"}"
+            quote="${value:0:1}"
+            if [ "$quote" = '"' ] || [ "$quote" = "'" ]; then
+              rest="${value:1}"
+              if [[ "$rest" != *"$quote"* ]]; then
+                echo "::error file=$file,line=$lineno::$name: unterminated $quote quote." >&2
+                exit 1
+              fi
+              value="${rest%%"$quote"*}"
+            else
+              value="${value%%[[:space:]]#*}"
+              value="${value%"${value##*[![:space:]]}"}"
+            fi
+            if [[ "$value" == *[[:cntrl:]]* ]]; then
+              echo "::error file=$file,line=$lineno::$name: control characters are not allowed in a value." >&2
+              exit 1
+            fi
+            settings+=("$name=$value")
+          done < "$file"
+          if [ "${#settings[@]}" -gt 0 ]; then
+            printf '%s\n' "${settings[@]}" >> "$GITHUB_ENV"
+          fi
+
+      - name: Resolve the image and the target
+        id: settings
+        run: |
+          for var in IMAGE_REPOSITORY RELEASE_NAME CHART_PATH CD GRAPH_AGENTS_CLI_SPEC; do
+            if [ -z "${!var:-}" ]; then
+              echo "::error file=.github/agent.env::$var is not set in .github/agent.env." >&2
+              exit 1
+            fi
+          done
+          if [ "$CD" != argocd ] && [ "$CD" != helm-push ]; then
+            echo "::error file=.github/agent.env::CD must be argocd or helm-push for this workflow, got '$CD'." >&2
+            exit 1
+          fi
+          if [[ "$IMAGE_REPOSITORY" == *CHANGE-ME* ]] || ! [[ "$IMAGE_REPOSITORY" =~ ^[A-Za-z0-9.-]+(:[0-9]+)?(/[a-z0-9._-]+)+$ ]]; then
+            echo "::error file=.github/agent.env::IMAGE_REPOSITORY must be <registry>/<path> in lowercase with no placeholder, got '$IMAGE_REPOSITORY'." >&2
+            exit 1
+          fi
+          TAG="${GITHUB_SHA::7}"
+          manifest=graph-agents-cli-manifest.yaml
+          NAMESPACE="$(yq -r '.environments.staging.namespace // ""' "$manifest")"
+          if [ -z "$NAMESPACE" ]; then
+            NAMESPACE="$(yq -r '.name // ""' "$manifest")-staging"
+          fi
+          if ! [[ "$NAMESPACE" =~ ^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$ ]]; then
+            echo "::error file=$manifest::Invalid staging namespace '$NAMESPACE'." >&2
+            exit 1
+          fi
+          # The kube context `deploy` uses; empty = the kubeconfig's current one.
+          KUBE_CONTEXT="$(yq -r '.environments.staging.context // ""' "$manifest")"
+          if [ -n "$KUBE_CONTEXT" ] && { ! [[ "$KUBE_CONTEXT" =~ ^[[:graph:]]+$ ]] || [[ "$KUBE_CONTEXT" == -* ]]; }; then
+            echo "::error file=$manifest::Invalid staging kube context '$KUBE_CONTEXT'." >&2
+            exit 1
+          fi
+          if ! [[ "$RELEASE_NAME" =~ ^[a-z0-9]([-a-z0-9]{0,51}[a-z0-9])?$ ]]; then
+            echo "::error file=.github/agent.env::Invalid RELEASE_NAME '$RELEASE_NAME'." >&2
+            exit 1
+          fi
+          {
+            echo "cd=${CD}"
+            echo "tag=${TAG}"
+            echo "image=${IMAGE_REPOSITORY}:${TAG}"
+            echo "chart_path=${CHART_PATH}"
+            echo "release=${RELEASE_NAME}"
+            echo "namespace=${NAMESPACE}"
+            echo "kube_context=${KUBE_CONTEXT}"
+            echo "graph_agents_cli_spec=${GRAPH_AGENTS_CLI_SPEC}"
+          } >> "$GITHUB_OUTPUT"
+          echo "REGISTRY_HOST=${IMAGE_REPOSITORY%%/*}" >> "$GITHUB_ENV"
+          echo "IMAGE=${IMAGE_REPOSITORY}:${TAG}" >> "$GITHUB_ENV"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to the registry
+        # GHCR works with the workflow token; other registries take REGISTRY_USERNAME / REGISTRY_PASSWORD secrets.
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY_HOST }}
+          username: ${{ secrets.REGISTRY_USERNAME || github.actor }}
+          password: ${{ secrets.REGISTRY_PASSWORD || secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile
+          push: true
+          tags: ${{ env.IMAGE }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  land_argocd:
+    # Pull-based: write the desired state and let Argo CD reconcile from main.
+    needs: build
+    if: needs.build.outputs.cd == 'argocd'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      # A pull request opened with the workflow token does not trigger pr_checks
+      # (GitHub never starts workflows from GITHUB_TOKEN events), so auto-merge
+      # would wait forever on a required check. Store a fine-grained PAT or a
+      # GitHub App token as the GH_PR_TOKEN repository secret to lift that limit.
+      # The merge it enables is a push to main that changes only
+      # values-staging.yaml, which paths-ignore above keeps from re-running this
+      # workflow.
+      GH_TOKEN: ${{ secrets.GH_PR_TOKEN || secrets.GITHUB_TOKEN }}
+      TAG: ${{ needs.build.outputs.tag }}
+      IMAGE: ${{ needs.build.outputs.image }}
+      CHART_PATH: ${{ needs.build.outputs.chart_path }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # Full history: the next step orders staging builds by commit ancestry.
+          fetch-depth: 0
+          # Branch pushes with the PR token too, so a regenerated branch re-runs
+          # pr_checks (a push made with the workflow token starts no workflow).
+          token: ${{ secrets.GH_PR_TOKEN || secrets.GITHUB_TOKEN }}
+
+      - name: Open the staging PR with auto-merge
+        # Same branch name as a workstation `graph-agents-cli deploy --env staging`
+        # (deploy/<env>/<short sha>). Requires branch protection on main to permit
+        # auto-merge for the token and pr_checks to be green.
+        # Every staging PR edits the same line, so two quick pushes would leave
+        # the second PR conflicting once the first merged. Instead each run
+        # closes the older staging PRs still open (staging only needs the newest
+        # build), then builds its branch on the latest main, and does nothing
+        # when main, or an open PR, already carries this build or a newer one:
+        # a re-run of an older build never moves staging back. The branch is
+        # bot-owned, so a re-run replaces it (the PR is created only when none
+        # is open).
+        run: |
+          values="${CHART_PATH}/values-staging.yaml"
+          BRANCH="deploy/staging/${TAG}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # True when commit $1 is an older ancestor of commit $2 (both known here).
+          older() {
+            local a b
+            a="$(git rev-parse --verify --quiet "${1}^{commit}")" || return 1
+            b="$(git rev-parse --verify --quiet "${2}^{commit}")" || return 1
+            [ "$a" != "$b" ] && git merge-base --is-ancestor "$a" "$b"
+          }
+          # Put the branch on the latest main; stop when main already deploys
+          # this build or a newer one.
+          sync_with_main() {
+            git fetch --quiet --no-tags origin +refs/heads/main:refs/remotes/origin/main
+            git checkout --quiet -B "$BRANCH" refs/remotes/origin/main
+            current="$(yq -r '.image.tag // ""' "$values")"
+            if [ "$current" = "$TAG" ]; then
+              echo "values-staging.yaml on main already deploys ${IMAGE}; nothing to open."
+              exit 0
+            fi
+            if [ -n "$current" ] && older "$GITHUB_SHA" "$current"; then
+              echo "main already deploys a newer build (${current}) to staging; nothing to open."
+              exit 0
+            fi
+          }
+
+          sync_with_main
+          open_prs="$(gh pr list --base main --state open --limit 200 --json number,headRefName --jq '.[] | "\(.number) \(.headRefName)"')"
+          while read -r number head; do
+            case "$head" in
+              deploy/staging/*) ;;
+              *) continue ;;
+            esac
+            if [ "$head" = "$BRANCH" ]; then
+              continue
+            fi
+            other="${head#deploy/staging/}"
+            if older "$GITHUB_SHA" "$other"; then
+              echo "A newer staging build is pending (#${number}, ${head}); nothing to open."
+              exit 0
+            fi
+            # A branch this step cannot order (a workstation tag) is left alone.
+            if older "$other" "$GITHUB_SHA"; then
+              gh pr close "$number" --delete-branch --comment "Superseded by ${IMAGE} (${BRANCH})." \
+                || echo "::warning::Could not close the superseded staging PR #${number} (${head})."
+            fi
+          done <<< "$open_prs"
+          # Whatever merged before those PRs closed is on main now.
+          sync_with_main
+          yq -i '.image.tag = strenv(TAG) | .image.tag style="double"' "$values"
+          git add "$values"
+          git commit --quiet -m "deploy(staging): image ${IMAGE}"
+          git push --force origin "$BRANCH"
+          if [ -z "$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[].number')" ]; then
+            gh pr create --base main --head "$BRANCH" \
+              --title "deploy(staging): ${TAG}" \
+              --body "Automated staging promotion of ${IMAGE}. Merges automatically once pr_checks passes."
+          fi
+          # --auto merges directly when already mergeable and is a no-op once merged;
+          # an "already enabled" rejection of the enable mutation is a success too.
+          gh pr merge --auto --squash "$BRANCH" \
+            || [ -n "$(gh pr view "$BRANCH" --json autoMergeRequest --jq '.autoMergeRequest.enabledAt // empty')" ]
+
+  deploy_helm_push:
+    # Push-based: a self-hosted runner inside the network runs helm through the
+    # CLI (helm and kubectl on its PATH). The cluster credentials are the
+    # DEPLOY_KUBECONFIG secret of the `staging` environment: an environment
+    # secret, never a repository secret, so only jobs that run in that
+    # environment (main only, per its deployment-branch rule) can read it.
+    needs: build
+    if: needs.build.outputs.cd == 'helm-push'
+    runs-on: self-hosted
+    environment: staging
+    permissions:
+      contents: read
+    env:
+      GRAPH_AGENTS_CLI_NO_UPDATE_CHECK: "1"
+      # The CLI's own `deploy`: no extension (committed, or installed on the
+      # runner) can replace it while it holds the cluster credentials.
+      GRAPH_AGENTS_CLI_DISABLE_OVERRIDES: "1"
+      IMAGE: ${{ needs.build.outputs.image }}
+      RELEASE: ${{ needs.build.outputs.release }}
+      NAMESPACE: ${{ needs.build.outputs.namespace }}
+      MANIFEST_CONTEXT: ${{ needs.build.outputs.kube_context }}
+      GRAPH_AGENTS_CLI_SPEC: ${{ needs.build.outputs.graph_agents_cli_spec }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      - name: Configure kubeconfig
+        # Written to the job's temporary directory (owner-only) and removed by
+        # the last step, whatever happens: nothing is left on the runner.
+        env:
+          DEPLOY_KUBECONFIG: ${{ secrets.DEPLOY_KUBECONFIG }}
+        run: |
+          if [ -z "$DEPLOY_KUBECONFIG" ]; then
+            echo "::error::DEPLOY_KUBECONFIG is empty: store the cluster credentials as the DEPLOY_KUBECONFIG secret of the staging environment (Settings > Environments > staging)." >&2
+            exit 1
+          fi
+          umask 077
+          printf '%s\n' "$DEPLOY_KUBECONFIG" > "$RUNNER_TEMP/kubeconfig"
+          echo "KUBECONFIG=$RUNNER_TEMP/kubeconfig" >> "$GITHUB_ENV"
+
+      - name: Resolve the kube context
+        # One context for the deploy and the checks after it, passed to both:
+        # the manifest's environments.staging.context when set, else the current
+        # context of DEPLOY_KUBECONFIG (what `deploy` itself would pick).
+        run: |
+          if ! command -v kubectl >/dev/null 2>&1; then
+            echo "::error::kubectl is not on the runner's PATH; the deploy and its checks need it." >&2
+            exit 1
+          fi
+          context="${MANIFEST_CONTEXT:-}"
+          if [ -z "$context" ]; then
+            context="$(kubectl config current-context 2>/dev/null || true)"
+          fi
+          if [ -z "$context" ]; then
+            echo "::error::No kube context: set environments.staging.context in graph-agents-cli-manifest.yaml or a current-context in DEPLOY_KUBECONFIG." >&2
+            exit 1
+          fi
+          if ! [[ "$context" =~ ^[[:graph:]]+$ ]] || [[ "$context" == -* ]]; then
+            echo "::error::Invalid kube context name '$context'." >&2
+            exit 1
+          fi
+          if ! kubectl config get-contexts "$context" >/dev/null 2>&1; then
+            echo "::error::Kube context '$context' is not in the DEPLOY_KUBECONFIG of the staging environment." >&2
+            exit 1
+          fi
+          echo "Kube context: $context"
+          echo "KUBE_CONTEXT=$context" >> "$GITHUB_ENV"
+
+      - name: Deploy to staging
+        # `deploy --image` in helm-push mode runs helm only (the image is already
+        # pushed), in the context resolved above; --yes: no prompt.
+        run: |
+          uvx --from "$GRAPH_AGENTS_CLI_SPEC" graph-agents-cli deploy --env staging --image "$IMAGE" --context "$KUBE_CONTEXT" --yes
+
+      - name: Verify the rollout
+        run: |
+          : "${NAMESPACE:?the build job resolved no namespace}" "${RELEASE:?the build job resolved no release}"
+          : "${KUBE_CONTEXT:?no kube context was resolved}"
+          # The cluster `deploy` just used (the same context).
+          kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" rollout status "deployment/$RELEASE" --timeout=300s
+          log="$RUNNER_TEMP/port-forward.log"
+          kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" port-forward "service/$RELEASE" :http > "$log" 2>&1 &
+          forward=$!
+          trap 'kill "$forward" 2>/dev/null || true' EXIT
+          port=""
+          for _ in $(seq 1 30); do
+            port="$(sed -n 's/^Forwarding from 127\.0\.0\.1:\([0-9][0-9]*\) .*/\1/p' "$log" | head -n 1)"
+            if [ -n "$port" ] || ! kill -0 "$forward" 2>/dev/null; then
+              break
+            fi
+            sleep 1
+          done
+          if [ -z "$port" ]; then
+            echo "::error::kubectl port-forward to service/$RELEASE failed: $(cat "$log")" >&2
+            exit 1
+          fi
+          for path in /health /ready; do
+            ok=""
+            for _ in $(seq 1 10); do
+              if curl --fail --silent --show-error --max-time 5 "http://127.0.0.1:${port}${path}"; then
+                ok=1
+                break
+              fi
+              sleep 3
+            done
+            echo
+            if [ -z "$ok" ]; then
+              echo "::error::${path} did not answer 2xx on the staging deployment ($NAMESPACE/$RELEASE)." >&2
+              exit 1
+            fi
+          done
+          echo "staging runs ${IMAGE} and answers /health and /ready."
+
+      - name: Remove kubeconfig
+        if: always()
+        run: rm -f "$RUNNER_TEMP/kubeconfig" "$RUNNER_TEMP/port-forward.log"

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/deployment/argocd/application-dev.yaml

@@ -0,0 +1,43 @@
+# Argo CD Application for the dev environment.
+# Argo reconciles from main, so nothing reaches the cluster until a PR merges.
+# The chart refuses to render until values-dev.yaml names an image tag
+# (`graph-agents-cli deploy --env dev` opens the PR that sets it): until then
+# Argo CD reports a comparison error and deploys nothing.
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: {{cookiecutter.project_name}}-dev
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  source:
+    # CHANGE-ME: the git URL of this repository.
+    repoURL: https://github.com/CHANGE-ME/{{cookiecutter.project_name}}.git
+    targetRevision: main
+    path: deployment/helm/{{cookiecutter.project_name}}
+    helm:
+      releaseName: {{cookiecutter.project_name}}
+      valueFiles:
+        - values.yaml
+        - values-dev.yaml
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: {{cookiecutter.project_name}}-dev
+  # The bundled Postgres's credentials Secret is generated on the first sync
+  # (Argo CD renders without cluster access, so every render would otherwise
+  # produce a new password the database volume no longer accepts): keep the
+  # live values. Only exists when postgresql.enabled (dev by default).
+  ignoreDifferences:
+    - kind: Secret
+      name: {{cookiecutter.project_name}}-postgresql-auth
+      jsonPointers:
+        - /data
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+      - RespectIgnoreDifferences=true

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/deployment/argocd/application-prod.yaml

@@ -0,0 +1,41 @@
+# Argo CD Application for the prod environment.
+# Argo reconciles from main, so nothing reaches the cluster until a PR merges.
+# The chart refuses to render until values-prod.yaml names an image tag
+# (promote-to-prod opens the PR that sets it).
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: {{cookiecutter.project_name}}-prod
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  source:
+    # CHANGE-ME: the git URL of this repository.
+    repoURL: https://github.com/CHANGE-ME/{{cookiecutter.project_name}}.git
+    targetRevision: main
+    path: deployment/helm/{{cookiecutter.project_name}}
+    helm:
+      releaseName: {{cookiecutter.project_name}}
+      valueFiles:
+        - values.yaml
+        - values-prod.yaml
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: {{cookiecutter.project_name}}-prod
+  # The bundled Postgres's credentials Secret is generated on the first sync
+  # (Argo CD renders without cluster access, so every render would otherwise
+  # produce a new password the database volume no longer accepts): keep the
+  # live values. Only exists when postgresql.enabled (dev by default).
+  ignoreDifferences:
+    - kind: Secret
+      name: {{cookiecutter.project_name}}-postgresql-auth
+      jsonPointers:
+        - /data
+  # Production has NO automated sync (a human syncs it): after the values-prod.yaml
+  # PR merges, an operator syncs the application in Argo CD.
+  syncPolicy:
+    syncOptions:
+      - CreateNamespace=true
+      - RespectIgnoreDifferences=true

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/deployment/argocd/application-staging.yaml

@@ -0,0 +1,43 @@
+# Argo CD Application for the staging environment.
+# Argo reconciles from main, so nothing reaches the cluster until a PR merges.
+# The chart refuses to render until values-staging.yaml names an image tag
+# (the staging workflow opens the PR that sets it): until then Argo CD reports
+# a comparison error and deploys nothing.
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: {{cookiecutter.project_name}}-staging
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  source:
+    # CHANGE-ME: the git URL of this repository.
+    repoURL: https://github.com/CHANGE-ME/{{cookiecutter.project_name}}.git
+    targetRevision: main
+    path: deployment/helm/{{cookiecutter.project_name}}
+    helm:
+      releaseName: {{cookiecutter.project_name}}
+      valueFiles:
+        - values.yaml
+        - values-staging.yaml
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: {{cookiecutter.project_name}}-staging
+  # The bundled Postgres's credentials Secret is generated on the first sync
+  # (Argo CD renders without cluster access, so every render would otherwise
+  # produce a new password the database volume no longer accepts): keep the
+  # live values. Only exists when postgresql.enabled (dev by default).
+  ignoreDifferences:
+    - kind: Secret
+      name: {{cookiecutter.project_name}}-postgresql-auth
+      jsonPointers:
+        - /data
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+      - RespectIgnoreDifferences=true

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/deployment/helm/{{cookiecutter.project_name}}/.helmignore

@@ -0,0 +1,14 @@
+.DS_Store
+.git/
+.gitignore
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+.project
+.idea/
+*.tmproj
+.vscode/
+# Documentation, not part of the packaged chart.
+examples/

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/deployment/helm/{{cookiecutter.project_name}}/Chart.yaml

@@ -0,0 +1,21 @@
+apiVersion: v2
+name: {{cookiecutter.project_name}}
+description: Helm chart for the {{cookiecutter.project_name}} LangGraph agent (graph-agents-cli)
+type: application
+version: 0.1.0
+appVersion: "0.1.0"
+# Exact versions, so every `helm dependency build` resolves the same charts.
+# Their images are pinned by digest in values.yaml (see the note there on the
+# Bitnami catalogue and how to use another chart or an external database).
+dependencies:
+  # Optional in-cluster Postgres for dev (values-dev.yaml enables it). Staging
+  # and prod use an external database supplied through the Secret.
+  - name: postgresql
+    version: "18.11.6"
+    repository: oci://registry-1.docker.io/bitnamicharts
+    condition: postgresql.enabled
+  # Redis is only needed by the langgraph-server runtime.
+  - name: redis
+    version: "28.2.3"
+    repository: oci://registry-1.docker.io/bitnamicharts
+    condition: redis.enabled