Add trace-based behavioral tests with Monocle Test Tools

.env.example

@@ -60,6 +60,11 @@ INFOQUEST_API_KEY=your-infoquest-api-key
 # when you run Gateway workers outside the bundled deploy script.
 # DEER_FLOW_INTERNAL_AUTH_TOKEN=your-shared-internal-token
 
+# Provisioner API key for sandbox authentication (required when using provisioner/K8s sandbox mode).
+# The same value must be set on the provisioner container and in config.yaml sandbox.provisioner_api_key.
+# Generate: openssl rand -hex 32
+# PROVISIONER_API_KEY=your-provisioner-api-key
+
 # ── Frontend SSR → Gateway wiring ─────────────────────────────────────────────
 # The Next.js server uses these to reach the Gateway during SSR (auth checks,
 # /api/* rewrites). They default to localhost values that match `make dev` and

.github/workflows/chart.yaml

@@ -0,0 +1,87 @@
+name: Publish Helm Chart
+
+# Publishes the DeerFlow Helm chart as an OCI artifact to GHCR alongside the
+# container images (see container.yaml). Triggers on the same `v*` tags.
+#
+# On pull requests touching the chart or config.example.yaml, `validate-chart`
+# runs lint + template render + a config_version drift check (the chart's
+# embedded config_version must not lag config.example.yaml) so a broken or
+# stale chart fails the PR, not the release.
+#
+# Users then install with:
+#   helm install deer-flow oci://ghcr.io/${{ owner }}/deer-flow --version <ver>
+
+on:
+  push:
+    tags:
+      - "v*"
+  pull_request:
+    paths:
+      - "deploy/helm/deer-flow/**"
+      - "config.example.yaml"
+      - ".github/workflows/chart.yaml"
+      - "scripts/check_config_version.sh"
+
+jobs:
+  validate-chart:
+    # Runs on PRs and release tags: catch a broken render or a stale
+    # config_version before merge / publish. A broken chart published under a
+    # vX.Y.Z tag is an immutable OCI artifact (GHCR won't let you overwrite
+    # --version), so a regression must fail here, not on install.
+    if: github.event_name == 'pull_request' || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 #v6.0.3
+
+      # ubuntu-latest ships with helm 3 preinstalled - no setup-helm action needed.
+      - name: Lint chart
+        run: helm lint deploy/helm/deer-flow
+      - name: Validate templates render
+        run: helm template deer-flow deploy/helm/deer-flow --include-crds >/dev/null
+
+      # The chart's `config:` block embeds a config_version that must not fall
+      # behind config.example.yaml. A stale version is silent in-cluster (the
+      # image ships no example to compare against, so _check_config_version
+      # never warns) but means the chart's config is authored against an older
+      # schema. Bump it in values.yaml and the README example. config_version
+      # gates no runtime behavior - it only drives the outdated-warning - so a
+      # bare version bump needs no field changes. Logic lives in
+      # scripts/check_config_version.sh (shared with nightly.yaml).
+      - name: config_version drift check
+        run: bash scripts/check_config_version.sh
+
+  verify-versions:
+    # Gate the release: every version source must match the v* tag. A forgotten
+    # bump in Chart.yaml, pyproject.toml, or package.json fails here and skips
+    # the publish. See scripts/verify_versions.sh.
+    if: startsWith(github.ref, 'refs/tags/v')
+    uses: ./.github/workflows/verify-versions.yml
+
+  publish-chart:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [verify-versions, validate-chart]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 #v6.0.3
+
+      - name: Log in to GHCR
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" | \
+            helm registry login ghcr.io -u ${{ github.actor }} --password-stdin
+
+      - name: Package chart
+        run: helm package deploy/helm/deer-flow --destination ./packages
+
+      - name: Push chart to GHCR
+        run: |
+          for pkg in ./packages/*.tgz; do
+            echo "--- pushing $pkg"
+            helm push "$pkg" oci://ghcr.io/${{ github.repository_owner }}
+          done

.github/workflows/container.yaml

@@ -6,8 +6,14 @@ on:
       - "v*"
 
 jobs:
+  verify-versions:
+    # Gate the release: every version source must match the v* tag. A forgotten
+    # bump in Chart.yaml, pyproject.toml, or package.json fails here and skips
+    # all image builds. See scripts/verify_versions.sh.
+    uses: ./.github/workflows/verify-versions.yml
 
   backend-container:
+    needs: verify-versions
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -19,7 +25,7 @@ jobs:
       IMAGE_NAME: ${{ github.repository }}-backend
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 #v6.0.3
       - name: Log in to the Container registry
         uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 #v3.4.0
         with:
@@ -45,15 +51,22 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          # Bake the `postgres` extra into the published image so multi-replica
+          # deployments (K8s/Helm) can use shared Postgres persistence instead of
+          # file-based SQLite. sqlite/redis-only single-replica setups still work;
+          # this only adds the Postgres driver. See backend/Dockerfile `UV_EXTRAS`.
+          build-args: |
+            UV_EXTRAS=postgres
 
       - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be #v2.4.0
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
           subject-digest: ${{ steps.push.outputs.digest }}
           push-to-registry: true
 
   frontend-container:
+    needs: verify-versions
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -66,7 +79,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 #v6.0.3
       - name: Log in to the Container registry
         uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 #v3.4.0
         with:
@@ -94,7 +107,55 @@ jobs:
           labels: ${{ steps.meta.outputs.labels }}
 
       - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be #v2.4.0
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+
+  provisioner-container:
+    needs: verify-versions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    env:
+      REGISTRY: ghcr.io
+      IMAGE_NAME: ${{ github.repository }}-provisioner
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 #v6.0.3
+      - name: Log in to the Container registry
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 #v3.4.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 #v5.7.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=tag
+            type=ref,event=branch
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 #v6.18.0
+        with:
+          context: docker/provisioner
+          file: docker/provisioner/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be #v2.4.0
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
           subject-digest: ${{ steps.push.outputs.digest }}