feat(miner-deployment): add Kubernetes StatefulSet + Secret example for AMS fleet-mode

[davion-knight]

Adds k8s/ example manifests so an operator can run N isolated miner workers on a small cluster with kubectl (#5181). Built on the existing packages/gittensory-miner/Dockerfile image. (Resubmit of #5246 — fixes below.)

Fixes vs #5246 (which was auto-closed)

• Secret scanner (the hard blocker): miner-secret.example.yaml no longer commits placeholder credential strings — all values are empty (GITHUB_TOKEN: ""), and the README shows the kubectl create secret --from-literal path so real values never touch a file. The scanner triggers on the value, not intent.
• PVC write bug (reviewer-caught): added runAsGroup: 1000 + fsGroup: 1000 + fsGroupChangePolicy: OnRootMismatch so the non-root worker owns its PVC and can create SQLite files on a root-owned ReadWriteOnce volume.
• Addressed nits: commented storageClassName example in the volumeClaimTemplate; README notes on image-tag pinning and probes.

Why a StatefulSet (not a Deployment)

The miner keeps all state in local SQLite ledgers not safe for concurrent multi-pod access, so each replica needs its OWN volume. A Deployment shares one PVC across replicas; a StatefulSet's volumeClaimTemplates give each replica its own — the per-pod-isolation safety property this issue requires.

Contents

• k8s/miner-deployment.yaml — StatefulSet: configurable replicas, per-pod volumeClaimTemplate for /data/miner, non-root securityContext with fsGroup, resource requests/limits, continuous run worker, secret-sourced GITHUB_TOKEN (+ optional provider keys).
• k8s/miner-secret.example.yaml — Secret template (empty values) for GITHUB_TOKEN + optional provider keys.
• k8s/README.md — deploy sequence, scaling, and the StatefulSet/fsGroup rationale.

Validation

• test/unit/miner-k8s-manifests.test.ts (7 tests): real manifests are well-formed Kubernetes; a deliberately malformed manifest fails the validator; the per-pod-storage invariant holds (has volumeClaimTemplates, rejects a shared-PVC config, rejects a no-volumeClaimTemplates config).
• Manifests parse as valid YAML; prettier-clean. Static infra only — no src/** logic touched.

Closes #5181

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.34%. Comparing base (e6adb43) to head (c8e1e32).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5250   +/-   ##
=======================================
  Coverage   94.34%   94.34%           
=======================================
  Files         473      473           
  Lines       39982    39982           
  Branches    14576    14576           
=======================================
  Hits        37722    37722           
  Misses       1585     1585           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.29% <ø> (-0.15%)	⬇️
shard-2	34.71% <ø> (+0.12%)	⬆️
shard-3	32.14% <ø> (+0.05%)	⬆️
shard-4	31.85% <ø> (-0.26%)	⬇️
shard-5	33.57% <ø> (-0.24%)	⬇️
shard-6	45.07% <ø> (+0.21%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - fixes required

_{Review updated: 2026-07-12 11:48:11 UTC}

4 files · 2 AI reviewers · no blockers · readiness 100/100 · CI failing · blocked

🛑 Suggested Action - Fix Blockers

Review summary
This adds a StatefulSet + Secret example for running N isolated gittensory-miner workers on Kubernetes (#5181), correctly using per-pod volumeClaimTemplates instead of a shared PVC since the miner's SQLite ledgers aren't safe for concurrent multi-pod access. It addresses the two blockers from the prior submission (#5246): the Secret template now ships fully empty values instead of placeholder strings that trip secret scanners, and runAsGroup/fsGroup/fsGroupChangePolicy are added so the non-root container can actually write to the root-owned PVC. The accompanying test suite validates real manifest structure (not fabricated payloads) and specifically asserts the per-pod-storage invariant that motivated the StatefulSet choice, which is solid coverage for a static-infra change.

Nits — 5 non-blocking

• k8s/miner-deployment.yaml pins image: gittensory-miner:latest with default imagePullPolicy: Always — the README calls this out as a known tradeoff for the example, but consider adding an explicit imagePullPolicy line or a stronger warning since :latest + StatefulSet restarts can silently swap running-pod versions mid-fleet.
• test/unit/miner-k8s-manifests.test.ts's readManifest() resolves k8s/ via process.cwd(), so the test only passes when vitest is invoked from the repo root — worth a comment or path.resolve(__dirname, '../../k8s') to make it robust to invocation directory.
• No livenessProbe is defined (acknowledged in the README) — for an example meant to be copied into production this is reasonable but could ship a commented-out exec-based probe stub to make adoption easier.
• Consider referencing a concrete storageClassName example value relevant to the most common cloud providers in the commented-out line, since operators following the README literally may not know what to uncomment.
• In miner-secret.example.yaml, consider adding a brief inline note that stringData vs data differs (stringData auto-encodes) since this is the first secret example in the repo.

CI checks failing

• validate
• validate-code

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5181
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 111 registered-repo PR(s), 82 merged, 2 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	davion-knight; Gittensor profile; 111 PR(s), 2 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ Insufficient signal	risk: clean · value: insufficient-signal — Nothing measurable for the structural-improvement analyzers on this PR (e.g. no code files changed). LLM value judgment: moderate — The diff delivers a correctly-scoped, well-tested operator-facing Kubernetes example that resolves the specific reviewer-flagged defects (secret scanner trip, PVC write permissions) from the prior closed submission while staying tightly bound to the linked issue #5181.

Linked issue satisfaction

Addressed
The PR delivers both files (k8s/miner-deployment.yaml, k8s/miner-secret.example.yaml), configurable replicas, resource requests/limits with documented rationale, per-pod persistent storage guaranteed via volumeClaimTemplates (never a shared PVC), a k8s/README.md deploy/scale sequence, and an automated test suite validating manifest well-formedness plus the per-pod-storage invariant and a malformed

Review context

• Author: davion-knight
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 111 PR(s), 2 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-code)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.