Merge pull request #18 from Kilo-Org/ci/maintainer-app-committer

ci(release) use maintainer app committer

Author: St0rmz1

.github/actions/setup-git-committer/action.yml

@@ -0,0 +1,67 @@
+name: "Setup Git Committer"
+description: |
+  Exchange the kilo-maintainer GitHub App credentials for a short-lived
+  installation token, configure git to commit as `kilo-maintainer[bot]`,
+  and rewrite the origin remote so subsequent `git push` calls from the
+  workflow use the App token.
+
+  This is what lets the publish workflow push release commits to `main`
+  on a repo whose branch ruleset restricts direct pushes: the ruleset is
+  configured to bypass the `kilo-maintainer` App specifically, not the
+  generic `github-actions[bot]` identity every workflow shares.
+
+  Mirror of Kilo-Org/kilocode's action of the same name so the two repos
+  stay in sync on the committer identity.
+inputs:
+  kilo-maintainer-app-id:
+    description: "Kilo Maintainer GitHub App ID (numeric)"
+    required: true
+  kilo-maintainer-app-secret:
+    description: "Kilo Maintainer GitHub App private key (full PEM)"
+    required: true
+outputs:
+  token:
+    description: "Short-lived installation token for the kilo-maintainer App"
+    value: ${{ steps.apptoken.outputs.token }}
+  app-slug:
+    description: "App slug (expected: kilo-maintainer)"
+    value: ${{ steps.apptoken.outputs.app-slug }}
+runs:
+  using: "composite"
+  steps:
+    - name: Create app token
+      id: apptoken
+      uses: actions/create-github-app-token@v2
+      with:
+        app-id: ${{ inputs['kilo-maintainer-app-id'] }}
+        private-key: ${{ inputs['kilo-maintainer-app-secret'] }}
+        owner: ${{ github.repository_owner }}
+        # Scope the minted installation token to the current repo
+        # only, even when the kilo-maintainer App is installed on
+        # multiple repos in the org. Without this, the token would
+        # carry the App's full installation scope (e.g. both
+        # shell-security and kilocode) and a compromised workflow
+        # could push to unrelated repos.
+        repositories: ${{ github.event.repository.name }}
+
+    - name: Configure git user
+      shell: bash
+      run: |
+        slug="${{ steps.apptoken.outputs.app-slug }}"
+        git config --global user.name "${slug}[bot]"
+        git config --global user.email "${slug}[bot]@users.noreply.github.com"
+
+    # actions/checkout@v4 leaves an `http.https://github.com/.extraheader`
+    # config entry pointing at its own (GITHUB_TOKEN) authorization. Any
+    # `git push` would still use that header unless we drop it here —
+    # otherwise the App token we embed in the remote URL below would be
+    # shadowed and the bypass list wouldn't apply.
+    - name: Clear checkout auth
+      shell: bash
+      run: |
+        git config --local --unset-all http.https://github.com/.extraheader || true
+
+    - name: Configure git remote
+      shell: bash
+      run: |
+        git remote set-url origin https://x-access-token:${{ steps.apptoken.outputs.token }}@github.com/${{ github.repository }}

.github/workflows/publish.yml

@@ -34,9 +34,16 @@ concurrency: ${{ github.workflow }}-${{ github.ref }}-${{ inputs.channel }}-${{
 # id-token:write is required for npm provenance (SLSA attestation).
 # This workflow must run on GitHub-hosted runners (not Blacksmith) for
 # provenance to work — GitHub's OIDC token is only issued on their infra.
+#
+# contents: read is sufficient. Post-publish pushes to `main` are
+# authenticated by the kilo-maintainer App token (minted by the
+# setup-git-committer composite action), not by GITHUB_TOKEN. If a
+# future edit accidentally introduces a git/gh call that falls back
+# to GITHUB_TOKEN for a write, we want it to fail loudly here rather
+# than silently succeed with broader privilege.
 permissions:
   id-token: write
-  contents: write
+  contents: read
 
 jobs:
   publish:
@@ -136,11 +143,19 @@ jobs:
           echo "::warning::Could not verify $VERSION on the registry after 60s of polling. The publish step itself reported success; verification is informational only and the workflow will continue to the tag/release steps."
           exit 0
 
-      - name: Configure git identity
+      # Swap from the default `github-actions[bot]` identity to the
+      # `kilo-maintainer` GitHub App. Its installation token is what
+      # authorizes the post-publish push to `main` (the app is the sole
+      # principal on main's branch-ruleset bypass list). Using a
+      # purpose-built app keeps the bypass narrowly scoped to the
+      # publish flow instead of every workflow in this repo.
+      - name: Setup git committer (kilo-maintainer App)
+        id: committer
         if: steps.publish.outcome == 'success'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        uses: ./.github/actions/setup-git-committer
+        with:
+          kilo-maintainer-app-id: ${{ secrets.KILO_MAINTAINER_APP_ID }}
+          kilo-maintainer-app-secret: ${{ secrets.KILO_MAINTAINER_APP_SECRET }}
 
       # Atomic git/GH operations bundled into ONE step:
       # 1. Build the local commit (on main for stable, on detached HEAD for dev)
@@ -153,15 +168,25 @@ jobs:
       # All network operations have internal 3x retries with 5s backoff.
       # If anything fails after retries, the next step prints recovery
       # instructions.
+      # Explicit guard on BOTH publish AND committer succeeding. Without
+      # the committer half, a skipped committer step (e.g. someone edits
+      # its `if:` in the future) would leave `steps.committer.outputs.token`
+      # as an empty string — gh/git calls here would then fail with an
+      # opaque 401 instead of a clear "committer was skipped/failed"
+      # signal. Guard is cheap; diagnostic value is high.
       - name: Tag and release (post-publish)
         id: tag_and_release
-        if: steps.publish.outcome == 'success'
+        if: steps.publish.outcome == 'success' && steps.committer.outcome == 'success'
         env:
           TAG: ${{ steps.version.outputs.tag }}
           VERSION: ${{ steps.version.outputs.version }}
           CHANNEL: ${{ steps.version.outputs.channel }}
           PREVIEW: ${{ steps.version.outputs.preview }}
-          GH_TOKEN: ${{ github.token }}
+          # Use the kilo-maintainer App token for both `git push` (via the
+          # origin remote URL rewritten by the committer step above) and
+          # `gh release create` (this env var). The default GITHUB_TOKEN
+          # would be refused by main's branch ruleset.
+          GH_TOKEN: ${{ steps.committer.outputs.token }}
         run: |
           set -euo pipefail
 

.gitignore

@@ -2,6 +2,14 @@ node_modules/
 dist/
 *.tgz
 
+# Local release/bootstrap scripts that may contain npm classic tokens.
+# Never commit these. The real release path is `bun script/publish.ts`
+# driven by the GitHub Actions workflow (OIDC); any local `release.sh`
+# or `publish-local.sh` is a one-off bootstrap artifact.
+release.sh
+release-*.sh
+publish-local.sh
+
 # Local editor / agent state. Contributors using Claude Code, Cursor, or
 # similar tools get a per-machine settings file under .claude/. Ignore
 # the whole directory so nobody accidentally commits their local prefs

AGENTS.md

@@ -78,33 +78,30 @@ For full step-by-step release instructions see [RELEASING.md](./RELEASING.md).
 
 ### Branch protection and the release commit
 
-The publish workflow pushes commits and/or tags to `main` as
-`github-actions[bot]`, using the default `GITHUB_TOKEN`.
+The publish workflow pushes commits and/or tags to `main` as the
+`kilo-maintainer` GitHub App (the same App used by the kilocode
+monorepo), via a short-lived installation token minted by
+`.github/actions/setup-git-committer/action.yml`.
 
 - **Stable releases** (`channel=latest`) commit the `package.json` version
   bump back to `main` AND push the tag.
 - **Dev releases** (`channel=dev`) push only the tag (pointing at an
   orphan commit). `main` history stays clean.
 
-Once branch protection / repository rulesets are enabled on `main`, the
-`github-actions[bot]` actor **must be added to the ruleset's bypass actors
-list**, otherwise stable releases will fail at the push step _after_
-`npm publish` has already succeeded — leaving npm and GitHub out of sync.
-Dev releases are less affected (no commit to `main`) but still need tag
-push to be allowed, which most rulesets permit by default.
-
-This is a stopgap. The long-term plan is to adopt the same `kilo-maintainer`
-GitHub App pattern used by the kilocode monorepo
-(`kilocode/.github/actions/setup-git-committer/action.yml`), which signs
-release commits as the App and has explicit bypass permissions. That
-migration requires Kilo-Org admin access to install the App on this repo
-and configure secrets, so it's deferred until an org admin is available.
-
-Until then, release commits:
-
-- are authored by `github-actions[bot]`
-- are unsigned
-- bypass branch protection via the ruleset allowlist (not via an App token)
+`main`'s branch ruleset bypass list includes **only** the
+`kilo-maintainer` App — not the generic `github-actions[bot]`. This is
+deliberate: it keeps the bypass narrowly scoped to the publish flow
+(the one place that holds the App's private-key secret) instead of
+granting every workflow in the repo push-to-main capability.
+
+Release commits:
+
+- are authored by `kilo-maintainer[bot]`
+- are web-signed by GitHub (the App token commits go through the REST
+  API signing path, not a local git signature)
+- bypass branch protection via the App's ruleset bypass
+
+Full setup and troubleshooting in [RELEASING.md](./RELEASING.md#branch-protection).
 
 ## Code layout
 

RELEASING.md

@@ -4,54 +4,22 @@ Releases are cut from the `publish` workflow in GitHub Actions. There is no
 local release script, no automated release on push, and no changesets tool.
 Every release is a manual `workflow_dispatch`.
 
-> ⚠️ **Current state (as of 2026-04-17):** `github-actions[bot]` is not on
-> the `main` branch ruleset's bypass list. As a result, **every stable
-> (`channel=latest`) publish run will fail at the "Tag and release
-> (post-publish)" step** with `GH013: Repository rule violations found for
-refs/heads/main — Changes must be made through a pull request`.
+> **Committer identity:** post-publish commits to `main` are made by the
+> `kilo-maintainer` GitHub App (not the generic `github-actions[bot]`),
+> using a short-lived installation token minted inside the workflow. The
+> app is the sole principal on `main`'s branch-ruleset bypass list — see
+> [Branch protection](#branch-protection). If you see a release commit
+> authored by anyone else, something's wrong; stop and investigate.
 >
-> **Recovery after a failed stable run:**
+> **Required secrets** (already configured, documented here for
+> disaster-recovery reference):
 >
-> 1. Check what actually landed on origin:
+> - `KILO_MAINTAINER_APP_ID` — the numeric App ID.
+> - `KILO_MAINTAINER_APP_SECRET` — the App's private key (full PEM).
 >
->    ```bash
->    git fetch origin --tags
->    git ls-remote --tags origin "vX.Y.Z"                                 # tag?
->    gh release view "vX.Y.Z" --repo Kilo-Org/shell-security   # release?
->    ```
->
-> 2. **If the tag exists and only the GitHub release is missing** (the
->    typical outcome — tags aren't covered by the branch ruleset and
->    usually land even when the `main` push is rejected), create the
->    release against the existing tag:
->
->    ```bash
->    gh release create vX.Y.Z \
->      --repo Kilo-Org/shell-security \
->      --title vX.Y.Z \
->      --generate-notes \
->      --verify-tag
->    ```
->
->    `--verify-tag` makes `gh` fail fast if the tag is missing instead of
->    silently creating a new one at current `main` HEAD. That's the whole
->    recovery — no other steps needed.
->
-> 3. **If the tag is also missing** (rare), follow
->    [Scenario 4](#scenario-4-publish-succeeded-but-commit--tag-push-failed)
->    below. It rebuilds the release commit locally (you can't tag the
->    runner-side SHA; that commit lived only in the Actions runner),
->    tags, pushes, then creates the release. The workflow's
->    `Print recovery instructions on partial failure` step also prints
->    this full sequence inline in the failed run's logs for copy-paste.
->
-> After step 2 (common case), `main`'s `package.json` will be one version
-> behind. Leave it alone — `script/version.ts` computes the next version
-> from git tags, not from `package.json`, so the drift is cosmetic.
->
-> This banner can be removed once the ruleset bypass is configured (see
-> [Branch protection](#branch-protection)) or the workflow is refactored
-> so stable publishes don't push to `main` at all.
+> Both are consumed by `.github/actions/setup-git-committer/action.yml`.
+> The same pair is used in `Kilo-Org/kilocode`; regenerating the
+> private key there would require updating it here too.
 
 ## Channels
 
@@ -282,9 +250,9 @@ This is the most dangerous failure mode. Symptom: `npm publish` succeeds
 step passes, but the workflow fails at the **"Commit version bump (stable
 only)"** or **"Tag release"** step with a `remote rejected` error.
 
-Most common cause: branch protection on `main` does not include
-`github-actions[bot]` in the bypass actors list. See **Branch protection**
-below.
+Most common cause: `main`'s branch ruleset bypass list does not include
+the `kilo-maintainer` GitHub App, or the App's installation token is
+expired/revoked. See **Branch protection** below.
 
 Recovery steps:
 
@@ -329,37 +297,38 @@ Recovery steps:
    # Add --prerelease for dev releases.
    ```
 
-5. Fix the underlying cause (branch protection bypass) before the next release.
+5. Verify the App token, App installation, and bypass list are still
+   valid (see **Branch protection** below) before the next release.
 
 ## Branch protection
 
-When branch protection / rulesets are enabled on `main`, the
-`github-actions[bot]` actor **must** be added to the ruleset's bypass actors
-list. Without it, the publish workflow's stable-channel commit step fails,
-triggering the recovery procedure above.
-
-> **Status today:** the `Main branch protection` ruleset on this repo
-> (`Settings → Rules → Rulesets`) is active but does NOT include
-> `github-actions[bot]` as a bypass actor. This is why the banner at the
-> top of this document describes the manual recovery step as expected
-> behavior for every stable publish. Two viable durable fixes, pick one:
->
-> 1. **Add the bot to the bypass list** (Settings → Rules → the ruleset
->    → Bypass list → add the `github-actions` app with bypass mode
->    `Always`). Fastest; keeps the current workflow unchanged.
-> 2. **Refactor the stable publish path** to match the dev-channel flow:
->    detach HEAD, commit, tag, push only the tag — never touch `main`.
->    Keeps the ruleset strict with no carve-outs; the trade-off is that
->    `main`'s `package.json` version drifts behind the latest release
->    (cosmetic only, since `version.ts` reads from tags).
-
-Dev-channel publishes don't push to `main` (only push the tag), so they're
-less affected by branch protection on `main` itself. The tag push still
-needs to be allowed — most rulesets allow tag pushes by default, but if
-yours blocks them, allowlist `github-actions[bot]` for tag operations too.
-
-See [AGENTS.md](./AGENTS.md#branch-protection-and-the-release-commit) for the
-longer-term plan to replace the bot bypass with a dedicated GitHub App.
+The `Main branch protection` ruleset on `main` (Settings → Rules →
+Rulesets) restricts direct pushes. The publish workflow bypasses this
+restriction by authenticating as the `kilo-maintainer` GitHub App rather
+than the default `github-actions[bot]`. Requirements for this to work:
+
+1. **`kilo-maintainer` App is installed on `Kilo-Org/shell-security`.**
+   Verify at Settings → GitHub Apps → Installed GitHub Apps. The App is
+   also installed on `Kilo-Org/kilocode`; same App, same credentials.
+2. **Two secrets exist in this repo** (or at org level, exposed to this
+   repo): `KILO_MAINTAINER_APP_ID` (numeric) and `KILO_MAINTAINER_APP_SECRET`
+   (full PEM private key). Regenerating the App's private key requires
+   updating `KILO_MAINTAINER_APP_SECRET` in every repo that uses it.
+3. **Bypass actor configured on the ruleset.** Settings → Rules →
+   `Main branch protection` → **Bypass list** must include the
+   `kilo-maintainer` App with bypass mode `Always`. Do NOT add the
+   generic `github-actions` app — that would grant bypass to every
+   workflow in the repo; the point of using the dedicated app is
+   to keep the bypass narrowly scoped to the publish flow.
+
+If a stable publish fails at the push step and all three above are in
+place, check the workflow run's `Setup git committer` step output — a
+revoked installation or an expired/rotated private key would fail there
+rather than at the push.
+
+Dev-channel publishes don't touch `main` (they push only the tag via an
+orphan commit), so they don't depend on item 3 above — but they still
+need items 1 and 2 for the same token minting flow.
 
 ## First publish of a newly-named npm package (OIDC bootstrap)