@rizom/ops 0.2.0-alpha.285 → 0.2.0-alpha.287

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.285",
+  "version": "0.2.0-alpha.287",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",

package/templates/rover-pilot/.github/workflows/upgrade.yml

@@ -12,8 +12,7 @@ on:
     - cron: "17 6 * * 1-5"
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 concurrency:
   group: upgrade
@@ -23,7 +22,21 @@ jobs:
   upgrade:
     runs-on: ubuntu-latest
     steps:
+      - name: Require upgrade App configuration
+        env:
+          APP_ID: ${{ vars.OPS_UPGRADE_APP_ID }}
+        run: |
+          if [ -z "$APP_ID" ]; then
+            echo "OPS_UPGRADE_APP_ID is not set." >&2
+            echo "Configure the upgrade GitHub App as described in docs/operator-playbook.md." >&2
+            exit 1
+          fi
+
+      # No credential is persisted in .git/config while the workflow installs
+      # and executes a freshly published @rizom/ops package.
       - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
 
       - uses: oven-sh/setup-bun@v2
 
@@ -35,14 +48,32 @@ jobs:
           VERSION_INPUT: ${{ inputs.version }}
         run: bunx brains-ops upgrade . --to "${VERSION_INPUT:-latest}"
 
-      - name: Open upgrade PR
-        env:
-          GH_TOKEN: ${{ github.token }}
+      - name: Detect upgrade changes
+        id: upgrade-changes
         run: |
           if [ -z "$(git status --porcelain)" ]; then
             echo "Already up to date."
-            exit 0
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
           fi
+
+      - name: Create repository-scoped upgrade token
+        if: steps.upgrade-changes.outputs.changed == 'true'
+        id: upgrade-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.OPS_UPGRADE_APP_ID }}
+          private-key: ${{ secrets.OPS_UPGRADE_APP_PRIVATE_KEY }}
+          permission-contents: write
+          permission-pull-requests: write
+          permission-workflows: write
+
+      - name: Open upgrade PR
+        if: steps.upgrade-changes.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.upgrade-token.outputs.token }}
+        run: |
           VERSION=$(bun -e 'console.log(JSON.parse(await Bun.file("package.json").text()).devDependencies["@rizom/ops"])')
           BRANCH="ops/upgrade-rizom-ops-$VERSION"
           git config user.name "github-actions[bot]"
@@ -50,9 +81,14 @@ jobs:
           git checkout -B "$BRANCH"
           git add -A
           git commit -m "chore(ops): upgrade @rizom/ops to $VERSION"
-          git push --force -u origin "$BRANCH"
+          git push --force \
+            "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
+            "$BRANCH"
+          if [ -n "$(gh pr list --head "$BRANCH" --state open --json number --jq '.[].number')" ]; then
+            echo "PR already open for $BRANCH"
+            exit 0
+          fi
           gh pr create \
             --title "chore(ops): upgrade @rizom/ops to $VERSION" \
             --body "Automated operator tooling upgrade. Review the scaffold diff, then merge; deploys stay operator-dispatched." \
-            --head "$BRANCH" \
-            || echo "PR already open for $BRANCH"
+            --head "$BRANCH"

package/templates/rover-pilot/README.md

@@ -51,4 +51,6 @@ When a push changes only deploy contract files, CI prints `No affected user conf
 
 `render` owns the observational `views/users.md` projection. Reconcile owns generated per-user config and never rewrites observed status rows.
 
+The Upgrade workflow uses a repository-scoped GitHub App token because an Actions `GITHUB_TOKEN` cannot update generated files under `.github/workflows/`. Checkout persists no credential, and the App token is minted only after the freshly published tooling finishes and only when there is a change to push. Configure the App and its `OPS_UPGRADE_APP_ID` Actions variable and `OPS_UPGRADE_APP_PRIVATE_KEY` Actions secret as described in `docs/operator-playbook.md`. If token creation or the upgrade push fails, stop; do not substitute an operator's personal credentials.
+
 Use `docs/canonical-crossover-record.md` to record exact forward and rollback artifact pins before an approved crossover window.

package/templates/rover-pilot/docs/operator-playbook.md

@@ -120,12 +120,25 @@ Preview hosts use the shape `<handle>-preview.rizom.ai`, so one wildcard origin
 
 ## Upgrading operator behavior
 
-When `@rizom/ops` changes the scaffolded deploy contract:
+The pilot repository pins `@rizom/ops` in `package.json`. The scheduled and manually dispatched Upgrade workflow owns routine upgrades to that pin. It refreshes the scaffold on a branch and opens a reviewable PR; it does not change runtime desired state or authorize a deployment.
 
-1. bump `@rizom/ops` in `package.json`
-2. rerun the relevant scaffold/reconcile flow
-3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
-4. commit the updated deploy artifacts together
+Because scaffold refreshes can update `.github/workflows/*`, the workflow must not push with its Actions `GITHUB_TOKEN`. Configure a dedicated GitHub App:
+
+1. Install it only on this pilot repository.
+2. Grant repository permissions `Contents: Read and write`, `Pull requests: Read and write`, and `Workflows: Read and write`; grant nothing else.
+3. Store its App ID as the repository Actions variable `OPS_UPGRADE_APP_ID`.
+4. Store its private key as the repository Actions secret `OPS_UPGRADE_APP_PRIVATE_KEY`.
+
+The workflow explicitly requests only those three permissions. Checkout persists no credential. After the freshly published `@rizom/ops` finishes, the workflow checks whether it produced a change; only then does it mint a short-lived, repository-scoped App token for the push-and-open-PR steps. A credential that can rewrite `.github/workflows/` therefore does not exist while upgraded package code runs.
+
+If `OPS_UPGRADE_APP_ID` is unset, or token creation, branch push, or PR creation fails, the run stops with a non-zero status. Repair the CI credential path; never fall back to an operator's personal SSH key or token.
+
+Adopting this credential flow in an existing pilot repository requires one explicitly reviewed bootstrap PR because the old Upgrade workflow cannot update itself. After that merge, routine upgrades run entirely in CI:
+
+1. dispatch Upgrade with an exact version, or let its schedule select `latest`;
+2. review the generated package, lockfile, deploy-script, and workflow diff;
+3. merge the upgrade PR only after its checks pass;
+4. change runtime desired state separately through the approved canary or fleet rollout flow.
 
 ## Canonical verification notes