hyperi-ci 2.2.2__tar.gz → 2.3.7__tar.gz

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/.github/workflows/python-ci.yml

@@ -162,6 +162,26 @@ jobs:
     strategy:
       matrix:
         os: ${{ fromJson(startsWith(github.head_ref || github.ref_name, 'renovate/') && format('["{0}"]', vars.GH_RUNNER_RENOVATE || 'ubuntu-latest') || (inputs.runner-mode || vars.GH_RUNNER_MODE) == 'free' && '["ubuntu-latest"]' || inputs.test-matrix || format('["{0}"]', inputs.runner-test || vars.GH_RUNNER_PYTHON || vars.GH_RUNNER_DEFAULT || 'ubuntu-latest')) }}
+    # Service containers required by integration tests.
+    # Always-on: harmless overhead for consumers that don't use them
+    # (job runs `psql` etc. against localhost ports). pylib's
+    # tests/conftest.py postgres fixture finds these via the
+    # `postgresql://postgres:postgres@localhost:5432/hyperi_pylib_test`
+    # DSN; matches pylib's docker-compose.postgres.yml.
+    services:
+      postgres:
+        image: postgres:18-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: hyperi_pylib_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d hyperi_pylib_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
     steps:
       - name: Docker Hub login
         if: ${{ vars.DOCKERHUB_USERNAME != '' }}

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/.github/workflows/rust-ci.yml

@@ -91,9 +91,13 @@ concurrency:
 env:
   HYPERCI_PUBLISH_TARGET: ${{ inputs.publish-target }}
   HYPERCI_INSTALL: uvx --no-cache --refresh hyperi-ci
-  # When dispatched with a tag, this is a release-channel build —
-  # enables Tier 2 (PGO + BOLT) build optimisation.
-  HYPERCI_CHANNEL: ${{ inputs.tag && 'release' || '' }}
+  # When dispatched with a tag (legacy workflow_dispatch path) OR when
+  # the caller declared `publish-target: both` (new `hyperi-ci push
+  # --release` path), this is a release-channel build — enables Tier 2
+  # (PGO + BOLT) build optimisation. Pre-2026-05-20 this only matched
+  # the workflow_dispatch path; consumers on the new push-trigger flow
+  # silently fell through to spike → Tier 1. See plan note for context.
+  HYPERCI_CHANNEL: ${{ (inputs.tag != '' || inputs.publish-target == 'both') && 'release' || '' }}
 
 jobs:
   # ---------------------------------------------------------------------------

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/.gitignore

@@ -35,3 +35,6 @@ Thumbs.db
 
 # AI agent working files (not committed)
 docs/superpowers/
+
+# Git worktrees
+.worktrees/

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/CHANGELOG.md

@@ -1,3 +1,87 @@
+## [2.3.7](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.6...v2.3.7) (2026-05-20)
+
+
+### Bug Fixes
+
+* **push:** stage auto-modified lockfiles into release-marker commit ([e5e1dd7](https://github.com/hyperi-io/hyperi-ci/commit/e5e1dd73d56350f4e25ea75e4f27ea718c7930c2))
+
+## [2.3.6](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.5...v2.3.6) (2026-05-20)
+
+
+### Bug Fixes
+
+* **init:** suppress false-positive semgrep importlib.resources warning ([382f7b9](https://github.com/hyperi-io/hyperi-ci/commit/382f7b913eb3428f5ad307a202b07d012d7ebf71))
+
+## [2.3.5](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.4...v2.3.5) (2026-05-20)
+
+
+### Bug Fixes
+
+* **deployment:** D-rule cleanup in topology + cli docstrings ([88fc7c9](https://github.com/hyperi-io/hyperi-ci/commit/88fc7c9bf2fd779d78b29d160c076a0dba23ed66))
+
+## [2.3.4](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.3...v2.3.4) (2026-05-20)
+
+
+### Bug Fixes
+
+* **init:** add module docstring + finalise Raises section formatting ([d7f7bb4](https://github.com/hyperi-io/hyperi-ci/commit/d7f7bb4f54bc0a06b7932508922e0a58be437d71))
+
+## [2.3.3](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.2...v2.3.3) (2026-05-20)
+
+
+### Bug Fixes
+
+* **cli:** add hyperi-ci init-topology subcommand ([599fb0c](https://github.com/hyperi-io/hyperi-ci/commit/599fb0cc5075a7c066e7c6c0ff8fbfbd4bd1bdef))
+* **cli:** add hyperi-ci stitch subcommand ([38decd0](https://github.com/hyperi-io/hyperi-ci/commit/38decd0e155aca1846d59092d9127c3140a985c2))
+* **deployment:** add ChartVersionResolver with semver range matching ([6a90869](https://github.com/hyperi-io/hyperi-ci/commit/6a9086929292375d7521dc86a0ada6f4888e2121))
+* **deployment:** generate umbrella Chart.yaml with resolved deps ([e06a155](https://github.com/hyperi-io/hyperi-ci/commit/e06a155a1383cc7860c8dc586e5c287b5523de8a))
+* **deployment:** implement full stitch (values, glue, helm dep update + lint) ([944ef28](https://github.com/hyperi-io/hyperi-ci/commit/944ef280b84cca9f4042ffc7287b9c238719031c))
+* **deployment:** wire ORAS for OCI chart tag listing ([11069bf](https://github.com/hyperi-io/hyperi-ci/commit/11069bff3f8c6ef92eac1af702dd2248a6f678bf))
+* **helm:** add topology-mode to helm stage (stitcher integration) ([ca532d3](https://github.com/hyperi-io/hyperi-ci/commit/ca532d32f65ffdaa55ebb4bc84d423e63657c75d))
+* **init:** add gitops repo scaffolding templates ([1a3a519](https://github.com/hyperi-io/hyperi-ci/commit/1a3a519b72be300d9850dfddac067410f4f6a5ef))
+* **init:** add init_gitops module + CLI subcommand ([67d08a2](https://github.com/hyperi-io/hyperi-ci/commit/67d08a234e61820cc65ba1380214bb38cac6b3d2))
+* **init:** seed gitops docs with reference content ([79bab6b](https://github.com/hyperi-io/hyperi-ci/commit/79bab6b140735fade60a78cef014cdda20d0da31))
+
+## [2.3.2](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.1...v2.3.2) (2026-05-20)
+
+
+### Bug Fixes
+
+* **ci:** gate release channel on publish-target=both for new push-trigger path ([c25787b](https://github.com/hyperi-io/hyperi-ci/commit/c25787b38b726c2fe1fe9db843c9b2f5ce5b0dce))
+* **deps:** bump hyperi-pylib floor to >=2.28.2 (topology subsystem) ([3026bcc](https://github.com/hyperi-io/hyperi-ci/commit/3026bcc3f5f1722cc958e9ce939d0d4fc9919ece))
+
+## [2.3.1](https://github.com/hyperi-io/hyperi-ci/compare/v2.3.0...v2.3.1) (2026-05-20)
+
+
+### Bug Fixes
+
+* **ci:** add postgres services container to python-ci test job ([1d979fc](https://github.com/hyperi-io/hyperi-ci/commit/1d979fc0e2b633093a2b886ed40a8c4c1c307d70))
+* **init:** generate CONTRIBUTING.md template explaining the two paths ([35bd157](https://github.com/hyperi-io/hyperi-ci/commit/35bd157f4ec780088d864a0422da161534a5be4b))
+
+# [2.3.0](https://github.com/hyperi-io/hyperi-ci/compare/v2.2.3...v2.3.0) (2026-05-15)
+
+
+### Bug Fixes
+
+* docstring polish (D102/D105/D205/D401) on overlay framework ([249b525](https://github.com/hyperi-io/hyperi-ci/commit/249b525e724928f6fe4b70f88f6ad13c5fcff60b))
+* ruff cleanups (D413, D401, N802, E741) on overlay framework files ([b276ef5](https://github.com/hyperi-io/hyperi-ci/commit/b276ef5afd16cc31b3c75e919725dcc98d262322))
+* ruff format on overlay framework files ([78a84f5](https://github.com/hyperi-io/hyperi-ci/commit/78a84f5a3d8c985198e0136e8f2b7a51004674ce))
+* **test:** make feat-gate tests env-independent (clear HYPERCI_ALLOW_FEAT) ([7262309](https://github.com/hyperi-io/hyperi-ci/commit/726230953c0002fa3ef5733386748b11008c211a))
+
+
+### Features
+
+* deployment-artefact overlay framework + helm/argocd stages ([ff63b37](https://github.com/hyperi-io/hyperi-ci/commit/ff63b375e587346ae0340af808b53dcbd47dca57))
+
+## [2.2.3](https://github.com/hyperi-io/hyperi-ci/compare/v2.2.2...v2.2.3) (2026-05-13)
+
+
+### Bug Fixes
+
+* **deployment:** exclude self-name from tier detection ([f61921b](https://github.com/hyperi-io/hyperi-ci/commit/f61921b9b0dcfe36c3c1809b0bacbedee4c78386))
+* **deps:** declare typer explicitly in runtime dependencies ([895a4a6](https://github.com/hyperi-io/hyperi-ci/commit/895a4a637e2f7f55bd74e2276ddb51f9184fc7cd))
+* **deps:** remove editable pylib source override to unblock Dependabot graph ([a4f1b28](https://github.com/hyperi-io/hyperi-ci/commit/a4f1b28551758e0e1287bf931f60e52194076021))
+
 ## [2.2.2](https://github.com/hyperi-io/hyperi-ci/compare/v2.2.1...v2.2.2) (2026-05-13)
 
 

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: hyperi-ci
-Version: 2.2.2
+Version: 2.3.7
 Summary: HyperI CI/CD CLI tool — multi-language build, test, and publish automation
 License: Proprietary
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: hyperi-pylib[metrics]>=2.28.0
+Requires-Dist: hyperi-pylib[metrics]>=2.28.2
+Requires-Dist: oras>=0.2.42
 Requires-Dist: packaging>=26.0
 Requires-Dist: pydantic>=2.13
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.25

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/README.md

@@ -251,6 +251,9 @@ No code changes, no workflow changes.
 | `hyperi-ci run quality\|test\|build\|generate\|container\|publish` | Run a single stage locally |
 | `hyperi-ci init-contract --app-name <name>` | Scaffold `ci/deployment-contract.json` (Tier 3) |
 | `hyperi-ci emit-artefacts <output-dir>` | Generate Dockerfile + chart + ArgoCD app from contract |
+| `hyperi-ci stitch <dir>` | Compose a deployment topology into an umbrella Helm chart |
+| `hyperi-ci init-gitops <dir>` | Scaffold a new gitops monorepo |
+| `hyperi-ci init-topology <name>` | Scaffold a new topology in existing gitops repo |
 | `hyperi-ci check-commit --list` | Show all accepted commit types |
 | `hyperi-ci detect` | Show detected language |
 | `hyperi-ci config` | Show merged config |

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/STATE.md

@@ -2,6 +2,25 @@
 
 Static context for AI assistants. For tasks and progress see `TODO.md`.
 
+## HARD RULES (READ FIRST)
+
+### No "later branch fix" commits
+
+**Never add a commit on a feature branch that fixes / cleans up / corrects an
+earlier commit on the same branch (or in any parent branch you forked from).**
+
+If commits 1, 2, 3 land on a feature branch and commit 1 turns out to be
+sloppy, you DO NOT add commit 4 that says "fix the noise from commit 1". You
+go back, rewrite commits 1-3 atomically, and force-push the cleaned-up
+branch. Each commit on a branch MUST stand alone as a clean, atomic change.
+
+This stays true at least until the branch is opened as a formal upstream PR —
+and even then, prefer rebase-clean over apologetic follow-up commits.
+
+Pinned at top per Derek 2026-05-20.
+
+---
+
 ## Flaky Test = Fix the Test
 
 **CI runs are 20-30 minutes on Rust projects. Re-running a flaky test
@@ -274,11 +293,42 @@ uv run hyperi-ci push --no-ci        # Push, skip CI
 uv run hyperi-ci publish --list      # List unpublished version tags
 uv run hyperi-ci publish v1.3.0      # Retroactive: dispatch publish on existing tag
 uv run hyperi-ci check-commit --list # List accepted commit types
+uv run hyperi-ci stitch <dir>        # Compose a deployment topology into an umbrella Helm chart
+uv run hyperi-ci init-gitops <dir>   # Scaffold a new gitops monorepo
+uv run hyperi-ci init-topology <name> # Scaffold a new topology in existing gitops repo
 ```
 
 `--release` and `release` are kept as deprecated aliases of `--publish` /
 `publish` for back-compat; will be removed in v4.0.
 
+## Gitops & Helm Topology Stitching
+
+The `stitch` subcommand and associated `init-gitops` / `init-topology`
+commands support a **gitops workflow** for managing Helm deployments
+across multiple applications.
+
+- **`hyperi-ci stitch <topology-dir>`** — composes a deployment topology
+  into an umbrella Helm chart. Reads `<dir>/topology.yaml`, resolves
+  `apps[]` semver ranges against OCI registries, generates `Chart.yaml`
+  + `values.yaml` + glue templates, runs `helm dep update` + `helm lint`.
+  Output is ready for `helm package` or `helm repo add`.
+
+- **`hyperi-ci init-gitops <dir> [--org NAME]`** — scaffolds a new gitops
+  monorepo skeleton with `topologies/`, `argocd/`, `values/`, `terraform/`,
+  `docs/` (MkDocs Material), `.github/workflows/`, README, CODEOWNERS,
+  and LICENSE.
+
+- **`hyperi-ci init-topology <name> [--app NAME ...]`** — scaffolds a new
+  topology directory inside an existing gitops repo, creating `topology.yaml`,
+  `values.yaml`, `glue/`, and README.
+
+### Helm Stage Topology Mode
+
+The Helm stage gains a `topology_mode` opt-in (via `publish.helm.topology_mode: true`
+in `.hyperi-ci.yaml`) that switches from per-app chart emission to topology
+stitching for gitops-repo CI. When enabled, the stage calls `hyperi-ci stitch`
+instead of running per-app chart generators.
+
 `--bump-patch` / `--bump-minor` are for the case where you want to ship
 a release whose commits aren't release-worthy under conventional-commits
 rules (e.g. a docs-only PR you want to release, or a force-rebuild).

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/TODO.md

@@ -221,6 +221,31 @@ RUN hyperi-ci prime-image --distro noble --all
 
 ### High Priority
 
+- [ ] **GitOps repo bootstrap (`hyperi-io/gitops`)** — full spec at
+      [`docs/superpowers/specs/2026-05-15-gitops-repo-bootstrap-spec.md`](docs/superpowers/specs/2026-05-15-gitops-repo-bootstrap-spec.md).
+      Public monorepo, single ApplicationSet with git-generator scanning
+      `applications/*/*.yaml`, directory-per-env (no branch-per-env),
+      branch protection on `applications/*/prod.yaml`. Manual steps
+      (org admin creates repo + cluster admin applies bootstrap
+      ApplicationSet) plus an optional `hyperi-ci init-gitops`
+      subcommand to scaffold the initial layout. Lands in parallel
+      with overlay framework Phase 3 (ArgoCD overlays) — gitops repo
+      must exist before hyperi-ci can push Application YAMLs into it.
+
+- [ ] **Deployment-artefact overlay framework** — full spec at
+      [`docs/superpowers/specs/2026-05-15-deployment-overlay-framework-spec.md`](docs/superpowers/specs/2026-05-15-deployment-overlay-framework-spec.md).
+      Three-mode design (contract / contract+amendments / BYO) for
+      Dockerfile + Helm + ArgoCD. Phased: **Phase 1 Dockerfile**
+      unblocks `dfe-transform-vector` v1.0.13 release (currently uses
+      a per-consumer `emit_dockerfile()` stop-gap restored from the
+      eroded commit 2345818 pattern). Phase 2 Helm + Phase 3 ArgoCD
+      are designed but implement-on-pull. Distribution targets
+      decided 2026-05-15: containers → GHCR (existing), Helm →
+      GHCR OCI (`oci://ghcr.io/hyperi-io/helm-charts`), ArgoCD →
+      central public `hyperi-io/gitops` repo with ApplicationSet
+      git-generator on `applications/*/*.yaml`. Spec includes
+      bootstrap notes for the new gitops repo.
+
 - [ ] Validate TypeScript pipeline end-to-end (after Rust)
   - Standalone fixture: github.com/hyperi-io/ci-test-ts-app (cloned at /projects/ci-test-ts-app)
   - Need a real consumer TypeScript project to cut over

hyperi_ci-2.3.7/VERSION

@@ -0,0 +1 @@
+2.3.7

{hyperi_ci-2.2.2 → hyperi_ci-2.3.7}/pyproject.toml

@@ -18,11 +18,17 @@ dependencies = [
     # The [metrics] extra is required because pylib's __init__.py
     # eagerly imports hyperi_pylib.metrics.prometheus → psutil.
     # Architectural fix (lazy metrics import) is tracked in pylib.
-    "hyperi-pylib[metrics]>=2.28.0",
+    "hyperi-pylib[metrics]>=2.28.2",
+    "oras>=0.2.42",
     "packaging>=26.0",
     "pydantic>=2.13",
     "pyyaml>=6.0",
     "tomli-w>=1.2.0",
+    # typer is used directly by src/hyperi_ci/cli.py — declare
+    # explicitly rather than relying on the transitive pull from
+    # hyperi-pylib's CLI infra. If pylib ever drops typer, this
+    # keeps us pinned to a known surface.
+    "typer>=0.25",
 ]
 
 [project.scripts]
@@ -39,12 +45,16 @@ pattern = "(?P<version>.+)"
 [tool.hatch.build.targets.wheel]
 packages = ["src/hyperi_ci"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"src/hyperi_ci/gitops_templates" = "hyperi_ci/gitops_templates"
+
 [tool.ruff]
 line-length = 88
 target-version = "py312"
 extend-exclude = [
-    "test-projects",   # vendored fixture trees (node_modules, .venv etc.)
-    "hyperi-ai",       # submodule, not our code
+    "test-projects",                             # vendored fixture trees (node_modules, .venv etc.)
+    "hyperi-ai",                                 # submodule, not our code
+    "src/hyperi_ci/gitops_templates",            # template data files, not Python source
 ]
 
 [tool.ruff.lint]
@@ -83,8 +93,20 @@ source = ["hyperi_ci"]
 # Keep this low so `pytest --cov` reports without failing the run.
 fail_under = 30
 
-[tool.uv.sources]
-hyperi-pylib = { path = "/projects/hyperi-pylib", editable = true }
+# NOTE: no [tool.uv.sources] block here on purpose.
+#
+# Tempting to point `hyperi-pylib` at a local editable checkout
+# (/projects/hyperi-pylib) so dev changes flow through `uv sync`,
+# but that breaks two things:
+#   - Dependabot's update_graph job can't resolve the path inside its
+#     container — fails on every push to main, leaving the dep-graph
+#     stale and GitHub's vulnerability banner inaccurate.
+#   - Reproducibility for anyone whose checkout isn't at that exact
+#     path.
+#
+# For local pylib co-development, run from this repo:
+#   uv pip install -e /path/to/hyperi-pylib
+# Manual install is per-developer scratch state; not in pyproject.
 
 [dependency-groups]
 dev = [

hyperi_ci-2.3.7/src/hyperi_ci/argocd/__init__.py

@@ -0,0 +1,20 @@
+# Project:   HyperI CI
+# File:      src/hyperi_ci/argocd/__init__.py
+# Purpose:   ArgoCD Application generation + push into central GitOps repo
+#
+# License:   Proprietary - HYPERI PTY LIMITED
+# Copyright: (c) 2026 HYPERI PTY LIMITED
+"""ArgoCD stage: generate Application YAML + push into hyperi-io/gitops.
+
+Stage flow (per overlay-framework spec section 10.5):
+
+  1. Invoke consumer's ``emit-argocd`` subcommand
+  2. Apply ``publish.argocd.overlays`` to the YAML
+  3. Clone the GitOps repo into a temp dir
+  4. Write the Application YAML to ``applications/<app>/<env>.yaml``
+  5. git commit + push (or open a PR per env policy)
+
+The GitOps repo (hyperi-io/gitops) is the public single-source-of-truth
+for ArgoCD cluster state. Its bootstrap spec lives at
+``docs/superpowers/specs/2026-05-15-gitops-repo-bootstrap-spec.md``.
+"""

hyperi_ci-2.3.7/src/hyperi_ci/argocd/gitops_push.py

@@ -0,0 +1,241 @@
+# Project:   HyperI CI
+# File:      src/hyperi_ci/argocd/gitops_push.py
+# Purpose:   Clone GitOps repo, write Application YAML, commit + push (or PR)
+#
+# License:   Proprietary - HYPERI PTY LIMITED
+# Copyright: (c) 2026 HYPERI PTY LIMITED
+"""Push an ArgoCD Application YAML into the central GitOps repo.
+
+Modes per env config:
+
+* ``direct`` (default): clone main, write file, commit, push to main.
+  Used for dev / staging environments.
+* ``pr``: clone main, write file on a branch, push branch, open PR.
+  Used for prod environments where a human approver is required.
+
+Concurrency: relies on the GitHub Actions concurrency group at the
+workflow level to serialise gitops pushes per-app per-env. This module
+itself is single-shot (one push per invocation).
+
+Auth: requires ``GITOPS_TOKEN`` (preferred) or ``GITHUB_TOKEN``
+with ``contents: write`` to the gitops repo.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from hyperi_ci.common import error, info, success
+
+
+@dataclass(frozen=True, slots=True)
+class GitopsPushConfig:
+    """Per-call configuration for a gitops push."""
+
+    repo: str  # "hyperi-io/gitops"
+    path: str  # "applications/dfe-loader/dev.yaml"
+    content: str  # the Application YAML
+    commit_message: str
+    push_mode: str  # "direct" | "pr"
+    branch_main: str = "main"
+
+
+def push(cfg: GitopsPushConfig) -> int:
+    """Execute the push. Returns exit code."""
+    token = (
+        os.environ.get("GITOPS_TOKEN")
+        or os.environ.get("GITHUB_TOKEN")
+        or os.environ.get("GITHUB_WRITE_TOKEN")
+    )
+    if not token:
+        error(
+            f"No GITOPS_TOKEN / GITHUB_TOKEN in environment — can't push to {cfg.repo}"
+        )
+        return 1
+
+    info(f"  argocd: pushing {cfg.path} to {cfg.repo} (mode={cfg.push_mode})")
+
+    with tempfile.TemporaryDirectory(prefix="hyperi-gitops-") as tmpdir:
+        clone_dir = Path(tmpdir) / "gitops"
+        rc = _git_clone(cfg.repo, clone_dir, token=token)
+        if rc != 0:
+            return rc
+
+        target = clone_dir / cfg.path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        existing = target.read_text(encoding="utf-8") if target.exists() else None
+        if existing == cfg.content:
+            info(f"  argocd: {cfg.path} already up-to-date — no push needed")
+            return 0
+        target.write_text(cfg.content, encoding="utf-8", newline="\n")
+
+        if cfg.push_mode == "pr":
+            return _push_pr(
+                clone_dir=clone_dir,
+                target=target,
+                cfg=cfg,
+                token=token,
+            )
+        return _push_direct(clone_dir=clone_dir, cfg=cfg, token=token)
+
+
+# ---- internals ----------------------------------------------------------
+
+
+def _git_clone(repo: str, dest: Path, *, token: str) -> int:
+    """Clone via HTTPS + token. Shallow clone (depth=1) for speed."""
+    url = f"https://x-access-token:{token}@github.com/{repo}.git"
+    proc = _run_git(["clone", "--depth=1", "--no-tags", url, str(dest)], cwd=Path.cwd())
+    if proc.returncode != 0:
+        # Don't print the URL (contains the token).
+        error(f"git clone {repo} failed (exit {proc.returncode})")
+        if proc.stderr:
+            # Strip the token from any URLs in stderr.
+            sanitised = proc.stderr.replace(token, "***")
+            error(sanitised.rstrip())
+        return proc.returncode
+    _git_setup_identity(dest)
+    return 0
+
+
+def _git_setup_identity(repo: Path) -> None:
+    """Configure a default committer identity inside the cloned repo."""
+    actor = os.environ.get("GITHUB_ACTOR", "hyperi-ci")
+    email = f"{actor}@users.noreply.github.com"
+    _run_git(["config", "user.name", actor], cwd=repo, check=True)
+    _run_git(["config", "user.email", email], cwd=repo, check=True)
+
+
+def _push_direct(
+    *,
+    clone_dir: Path,
+    cfg: GitopsPushConfig,
+    token: str,
+) -> int:
+    rel = Path(cfg.path)
+    proc = _run_git(["add", str(rel)], cwd=clone_dir)
+    if proc.returncode != 0:
+        error(proc.stderr.rstrip() if proc.stderr else "git add failed")
+        return proc.returncode
+    proc = _run_git(["commit", "-m", cfg.commit_message], cwd=clone_dir)
+    if proc.returncode != 0:
+        # `nothing to commit` is a no-op success
+        if "nothing to commit" in (proc.stdout or "") + (proc.stderr or ""):
+            info("  argocd: nothing to commit — content unchanged")
+            return 0
+        error(proc.stderr.rstrip() if proc.stderr else "git commit failed")
+        return proc.returncode
+
+    proc = _run_git(["push", "origin", cfg.branch_main], cwd=clone_dir)
+    if proc.returncode != 0:
+        error(proc.stderr.replace(token, "***").rstrip())
+        return proc.returncode
+
+    success(f"  argocd: pushed {cfg.path} to {cfg.repo}@{cfg.branch_main}")
+    return 0
+
+
+def _push_pr(
+    *,
+    clone_dir: Path,
+    target: Path,
+    cfg: GitopsPushConfig,
+    token: str,
+) -> int:
+    """Create a branch, push it, open a PR via GitHub API."""
+    branch_name = (
+        f"hyperi-ci/{cfg.path.replace('/', '-').replace('.yaml', '')}"
+        f"-{int(time.time())}"
+    )
+    proc = _run_git(["checkout", "-b", branch_name], cwd=clone_dir)
+    if proc.returncode != 0:
+        error(proc.stderr.rstrip())
+        return proc.returncode
+
+    proc = _run_git(["add", cfg.path], cwd=clone_dir)
+    if proc.returncode != 0:
+        error(proc.stderr.rstrip())
+        return proc.returncode
+    proc = _run_git(["commit", "-m", cfg.commit_message], cwd=clone_dir)
+    if proc.returncode != 0:
+        if "nothing to commit" in (proc.stdout or "") + (proc.stderr or ""):
+            info("  argocd: nothing to commit on PR branch — no PR opened")
+            return 0
+        error(proc.stderr.rstrip())
+        return proc.returncode
+
+    proc = _run_git(["push", "origin", branch_name], cwd=clone_dir)
+    if proc.returncode != 0:
+        error(proc.stderr.replace(token, "***").rstrip())
+        return proc.returncode
+
+    return _open_pr(cfg=cfg, branch=branch_name, token=token)
+
+
+def _open_pr(*, cfg: GitopsPushConfig, branch: str, token: str) -> int:
+    """Open a GitHub PR via the REST API."""
+    title = cfg.commit_message.splitlines()[0]
+    body = (
+        f"Automated push from hyperi-ci.\n\n"
+        f"Updates `{cfg.path}` in this gitops repo.\n\n"
+        f"Merge to apply the change to the corresponding ArgoCD env.\n"
+    )
+    payload = {
+        "title": title,
+        "head": branch,
+        "base": cfg.branch_main,
+        "body": body,
+    }
+    cmd = [
+        "curl",
+        "-fsSL",
+        "-X",
+        "POST",
+        "-H",
+        f"Authorization: Bearer {token}",
+        "-H",
+        "Accept: application/vnd.github+json",
+        "-H",
+        "X-GitHub-Api-Version: 2022-11-28",
+        f"https://api.github.com/repos/{cfg.repo}/pulls",
+        "-d",
+        json.dumps(payload),
+    ]
+    proc = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+    if proc.returncode != 0:
+        error(proc.stderr.replace(token, "***").rstrip())
+        return proc.returncode
+    try:
+        pr = json.loads(proc.stdout)
+        url = pr.get("html_url")
+        success(f"  argocd: opened PR {url}")
+    except json.JSONDecodeError:
+        success(f"  argocd: PR opened (response: {proc.stdout[:200]})")
+    return 0
+
+
+def _run_git(
+    args: list[str], *, cwd: Path, check: bool = False
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=check,
+    )