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

graph_agents_cli/scaffold/deployment_targets/kubernetes/python/.github/workflows/promote-to-prod.yaml

@@ -0,0 +1,371 @@
+# 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.
+
+# Promote the staging image to production. Runs in the GitHub
+# `production` environment, which controls who may initiate a promotion, and
+# only from main. Image tags are the SHORT commit SHA (${GITHUB_SHA::7}), as
+# the staging workflow pushes them. According to CD in .github/agent.env:
+#   argocd:    `graph-agents-cli deploy --env prod --image ...` updates
+#              values-prod.yaml on deploy/prod/<tag> and opens a PR; it is NOT
+#              merged here. The merge (code-owner review, no self-approval,
+#              pr_checks green) is the single production gate. After the merge
+#              an operator syncs Argo CD, whose health checks (the readiness
+#              probe, /ready) show whether the rollout landed.
+#   helm-push: `graph-agents-cli deploy --env prod --image ...` on the
+#              self-hosted runner runs helm with the already pushed image, with
+#              the kubeconfig of the `production` environment, then verifies the
+#              rollout (rollout status, /health and /ready through a port-forward),
+#              both in one kube context (environments.prod.context, else the
+#              kubeconfig's current one).
+# This file is copied verbatim into the project (not rendered).
+
+name: promote-to-prod
+
+on:
+  workflow_dispatch:
+    inputs:
+      image_tag:
+        description: "Image tag (short commit SHA) to promote. Empty = the tag currently in values-staging.yaml."
+        required: false
+        default: ""
+
+concurrency:
+  group: production
+  cancel-in-progress: false
+
+jobs:
+  settings:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: read
+    outputs:
+      cd: ${{ steps.settings.outputs.cd }}
+      image: ${{ steps.settings.outputs.image }}
+      tag: ${{ steps.settings.outputs.tag }}
+      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 tag to promote
+        id: settings
+        # The dispatch input reaches the shell through `env`, never by expression
+        # interpolation into the script (that would let a collaborator run
+        # commands in the production-environment jobs below).
+        env:
+          IMAGE_TAG: ${{ inputs.image_tag }}
+        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="$IMAGE_TAG"
+          if [ -n "$TAG" ] && ! [[ "$TAG" =~ ^[0-9a-f]{7,40}$ ]]; then
+            echo "image_tag must be a short commit SHA (7-40 hex characters), got '$TAG'." >&2
+            exit 1
+          fi
+          if [ -z "$TAG" ]; then
+            TAG="$(yq -r '.image.tag // ""' "${CHART_PATH}/values-staging.yaml")"
+          fi
+          if [ -z "$TAG" ] || [ "$TAG" = "latest" ] || [ "$TAG" = "null" ]; then
+            echo "No promotable tag: pass image_tag or land a staging build first." >&2
+            exit 1
+          fi
+          # Docker tag grammar: no shell metacharacters or newlines can reach the outputs.
+          if ! [[ "$TAG" =~ ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$ ]]; then
+            echo "Invalid image tag: '$TAG'" >&2
+            exit 1
+          fi
+          manifest=graph-agents-cli-manifest.yaml
+          NAMESPACE="$(yq -r '.environments.prod.namespace // ""' "$manifest")"
+          if [ -z "$NAMESPACE" ]; then
+            NAMESPACE="$(yq -r '.name // ""' "$manifest")-prod"
+          fi
+          if ! [[ "$NAMESPACE" =~ ^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$ ]]; then
+            echo "::error file=$manifest::Invalid prod namespace '$NAMESPACE'." >&2
+            exit 1
+          fi
+          # The kube context `deploy` uses; empty = the kubeconfig's current one.
+          KUBE_CONTEXT="$(yq -r '.environments.prod.context // ""' "$manifest")"
+          if [ -n "$KUBE_CONTEXT" ] && { ! [[ "$KUBE_CONTEXT" =~ ^[[:graph:]]+$ ]] || [[ "$KUBE_CONTEXT" == -* ]]; }; then
+            echo "::error file=$manifest::Invalid prod 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"
+
+  open_prod_pr:
+    needs: settings
+    if: needs.settings.outputs.cd == 'argocd'
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      # `deploy` opens the pull request through gh with this token. A pull
+      # request opened with the workflow token does not trigger pr_checks
+      # (GitHub never starts workflows from GITHUB_TOKEN events); store a
+      # fine-grained PAT or a GitHub App token as GH_PR_TOKEN to lift that limit.
+      GH_TOKEN: ${{ secrets.GH_PR_TOKEN || secrets.GITHUB_TOKEN }}
+      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 PR token.
+      GRAPH_AGENTS_CLI_DISABLE_OVERRIDES: "1"
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+
+      - name: Open the production PR (merge is the gate)
+        # In argocd mode `deploy` never runs helm: it rewrites image.tag in
+        # values-prod.yaml, commits that one file on deploy/prod/<tag> from
+        # origin/main and opens (or updates) the pull request. The commit needs
+        # a git identity. --yes: no prompt (this runner has no cluster context).
+        env:
+          IMAGE: ${{ needs.settings.outputs.image }}
+          GRAPH_AGENTS_CLI_SPEC: ${{ needs.settings.outputs.graph_agents_cli_spec }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          uvx --from "$GRAPH_AGENTS_CLI_SPEC" graph-agents-cli deploy --env prod --image "$IMAGE" --yes
+
+  deploy_helm_push:
+    # The cluster credentials are the DEPLOY_KUBECONFIG secret of the
+    # `production` environment: an environment secret, never a repository
+    # secret, so only jobs that pass this environment's protection rules
+    # (required reviewers, main only) can read it.
+    needs: settings
+    if: needs.settings.outputs.cd == 'helm-push'
+    runs-on: self-hosted
+    environment: production
+    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.settings.outputs.image }}
+      RELEASE: ${{ needs.settings.outputs.release }}
+      NAMESPACE: ${{ needs.settings.outputs.namespace }}
+      MANIFEST_CONTEXT: ${{ needs.settings.outputs.kube_context }}
+      GRAPH_AGENTS_CLI_SPEC: ${{ needs.settings.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 production environment (Settings > Environments > production)." >&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.prod.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.prod.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 production environment." >&2
+            exit 1
+          fi
+          echo "Kube context: $context"
+          echo "KUBE_CONTEXT=$context" >> "$GITHUB_ENV"
+
+      - name: Deploy to production
+        # `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 prod --image "$IMAGE" --context "$KUBE_CONTEXT" --yes
+
+      - name: Verify the rollout
+        run: |
+          : "${NAMESPACE:?the settings job resolved no namespace}" "${RELEASE:?the settings 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 production deployment ($NAMESPACE/$RELEASE)." >&2
+              exit 1
+            fi
+          done
+          echo "production runs ${IMAGE} and answers /health and /ready."
+
+      - name: Remove kubeconfig
+        if: always()
+        run: rm -f "$RUNNER_TEMP/kubeconfig" "$RUNNER_TEMP/port-forward.log"