refactor(bots): extract shared bot-prelude composite across all 4 workflows

eric-wang-1990 · eric-wang-1990 · commit 356882d8ec9c · 2026-07-15T16:04:43.000-07:00
The four bot workflows duplicated ~4 setup steps (mint bot token, mint engine-scoped token, Setup Node, install engine). Factor them into a local ./.github/actions/bot-prelude composite (inputs: app-id/private-key + engine-ref; output: token). Each workflow keeps only what genuinely differs: its checkout, Setup Python (reviewer — interpreter only) vs setup-poetry (engineer — connector deps for pytest self-verify), and its run/publish tail. bot-prelude calls the existing local install-bot-engine. Behavior unchanged; token refs now come from steps.prelude.outputs.token. Headers refreshed to match. Engine feedback on the duplicated install-bot-engine noted in issue #104. Co-authored-by: Isaac Signed-off-by: eric-wang-1990 <e.wang@databricks.com>
diff --git a/.github/actions/bot-prelude/action.yml b/.github/actions/bot-prelude/action.yml
@@ -0,0 +1,75 @@
+# Shared prelude for the bot workflows — the steps identical across all four
+# (reviewer, reviewer-followup, engineer, engineer-followup):
+#   1. mint the bot's App installation token (this repo) — for PR/issue posting
+#   2. mint a SECOND token scoped to the engine repo (contents:read) — PAT-free
+#      auth for the private-engine install
+#   3. set up Node (the Claude Code CLI the SDK spawns)
+#   4. install the pinned engine + Claude SDK/CLI via the local install-bot-engine
+#      composite, authenticated by the engine-scoped token
+#
+# LOCAL composite (`uses: ./…`) — resolves against this checked-out repo, so it
+# works where a cross-repo `uses:` of the engine does NOT. Call it AFTER checkout
+# (a composite can't run the checkout that loads it) and AFTER Python/Poetry setup
+# (the engine `pip install` needs the interpreter present). What stays inline in
+# each workflow: checkout (differs per flow), Python-vs-Poetry (reviewer needs
+# only Python; engineer needs the connector's deps via setup-poetry), and the
+# run/publish tail.
+name: Bot prelude (tokens + Node + engine install)
+description: Mint the bot + engine-scoped App tokens, set up Node, and install the pinned engine (PAT-free). Shared by all four bot workflows.
+
+inputs:
+  app-id:
+    description: 'Bot App id (review-bot or engineer-bot) — mints the this-repo token used to post.'
+    required: true
+  private-key:
+    description: 'Bot App private key (PEM) for the same App.'
+    required: true
+  engine-ref:
+    description: 'Engine commit SHA (full 40-char) to install.'
+    required: true
+  engine-repo:
+    description: 'owner/name of the engine repo.'
+    required: false
+    default: 'databricks/databricks-bot-engine'
+
+outputs:
+  token:
+    description: 'The minted bot App installation token for THIS repo (post reviews / push fix branches / comment).'
+    value: ${{ steps.app-token.outputs.token }}
+
+runs:
+  using: composite
+  steps:
+    # This-repo token: the identity the bot acts as (post reviews, push the fix
+    # branch, comment). Exposed as the `token` output for the caller's run steps.
+    - name: Mint bot App token
+      id: app-token
+      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+      with:
+        app-id: ${{ inputs.app-id }}
+        private-key: ${{ inputs.private-key }}
+
+    # Engine-scoped token: a SECOND, per-run token scoped to ONLY the engine repo
+    # (contents:read), used to `pip install` the private engine with no stored
+    # PAT. Requires the same App installed on the engine repo with contents:read.
+    - name: Mint engine-scoped install token
+      id: engine-token
+      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+      with:
+        app-id: ${{ inputs.app-id }}
+        private-key: ${{ inputs.private-key }}
+        owner: databricks
+        repositories: databricks-bot-engine
+        permission-contents: read
+
+    - name: Setup Node (for the Claude Code CLI the SDK spawns)
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
+      with:
+        node-version: '20'
+
+    - name: Install engine + Claude SDK/CLI
+      uses: ./.github/actions/install-bot-engine
+      with:
+        engine-ref: ${{ inputs.engine-ref }}
+        engine-repo: ${{ inputs.engine-repo }}
+        engine-token: ${{ steps.engine-token.outputs.token }}
diff --git a/.github/workflows/engineer-bot-followup.yml b/.github/workflows/engineer-bot-followup.yml
@@ -5,10 +5,10 @@
 # catch-up mode, applies a fixup (or replies / marks blocked), and pushes to the
 # PR branch. Driven by this repo's .bot/ prompts.
 #
-# Like the author, this builds/runs the product, so it keeps its own job and
-# interleaves `poetry install` before the shared bot-run composite. Consumer
-# differences vs the engine dogfood: REF-mode install pinned to an engine SHA,
-# authenticated PAT-free by an engine-scoped App token minted below.
+# Like the author, this builds/runs the product (setup-poetry). Shared setup
+# (tokens + Node + engine install, PAT-free via an engine-scoped App token) is in
+# the local ./.github/actions/bot-prelude composite; this file owns checkout,
+# setup-poetry, and the followup run. Engine installed in REF mode pinned to a SHA.
 #
 # The gate below is the canonical label-gated form copied verbatim from the
 # engine dogfood (the single source of truth). It ANDs with the engine-side
@@ -85,14 +85,6 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      # Mint the engineer-bot token (this repo — pushes fixup commits, posts replies).
-      - name: Mint engineer-bot App token
-        id: setup
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
-        with:
-          app-id: ${{ secrets.ENGINEER_BOT_APP_ID }}
-          private-key: ${{ secrets.ENGINEER_BOT_APP_PRIVATE_KEY }}
-
       # Python + connector deps via the repo's OWN setup-poetry action (JFrog
       # mirror + poetry lock + install) — egress-safe, tolerates a stale lock.
       # The agent runs `poetry run python -m pytest tests/unit` to verify fixups.
@@ -101,37 +93,23 @@ jobs:
         with:
           python-version: '3.11'
 
-      - name: Setup Node (for the Claude Code CLI the SDK spawns)
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
-        with:
-          node-version: '20'
-
-      # PAT-free engine install: engine-scoped token (contents:read) from the
-      # same App creds.
-      - name: Mint engine-scoped install token
-        id: engine-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+      # Shared prelude: mint the engineer-bot token (pushes fixup commits, posts
+      # replies) + the engine-scoped token, set up Node, install the engine.
+      - name: Bot prelude (tokens + Node + engine install)
+        id: prelude
+        uses: ./.github/actions/bot-prelude
         with:
           app-id: ${{ secrets.ENGINEER_BOT_APP_ID }}
           private-key: ${{ secrets.ENGINEER_BOT_APP_PRIVATE_KEY }}
-          owner: databricks
-          repositories: databricks-bot-engine
-          permission-contents: read
-
-      # LOCAL composite (cross-repo `uses:` of the engine won't resolve here).
-      - name: Install engine + Claude SDK/CLI
-        uses: ./.github/actions/install-bot-engine
-        with:
           engine-ref: b6205fb502566d617a456ccf3c37f3e4e3072ccd
-          engine-token: ${{ steps.engine-token.outputs.token }}
 
       # Run the follow-up. Inlines the engine's bot-run env contract for
       # engineer:followup, plus the authenticated push remote bot-run would set
       # up (followup pushes fixup commits via a plain `git push`, which doesn't
       # consult GH_TOKEN; the checkout is persist-credentials:false).
       - name: Run engineer follow-up (catch-up over all unaddressed threads)
         env:
-          GH_TOKEN: ${{ steps.setup.outputs.token }}
+          GH_TOKEN: ${{ steps.prelude.outputs.token }}
           GITHUB_REPOSITORY: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
diff --git a/.github/workflows/engineer-bot.yml b/.github/workflows/engineer-bot.yml
@@ -4,14 +4,13 @@
 # the bug with a failing test, fixes the connector code, and opens a PR. Driven
 # by the bug-fix flow + this repo's .bot/ (config + prompts).
 #
-# Unlike the reviewer (a thin reusable-workflow caller), the engineer builds and
-# runs THIS repo's tests, so it keeps its own job and interleaves env-prep
-# (`poetry install`) before invoking the engine — a reusable workflow can't host
-# that. It mirrors the engine's dogfood engineer-bot.yml, with two consumer
-# differences: (1) REF-mode install pinned to an engine SHA, authenticated
-# PAT-free by an engine-scoped App token minted below; (2) an explicit
-# `poetry install` so the connector's own deps are present for `pytest`
-# self-verify (REF mode installs only the engine, not the product).
+# The engineer builds and runs THIS repo's tests, so it needs the connector's
+# deps installed (via setup-poetry) in addition to the engine. Shared setup
+# (mint tokens + Node + install the pinned engine, PAT-free) is factored into the
+# local ./.github/actions/bot-prelude composite; this file owns checkout,
+# setup-poetry, and the author/publish/comment tail. The engine is installed in
+# REF mode pinned to a SHA and authenticated PAT-free by an engine-scoped App
+# token (minted inside bot-prelude).
 #
 # SECURITY: the trigger is a label only maintainers can apply — issue BODIES are
 # untrusted input, so the gate is who-can-label, not the content. The issue body
@@ -60,44 +59,29 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      # Mint the engineer-bot token (this repo — pushes the fix branch, comments).
-      - name: Mint engineer-bot App token
-        id: setup
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
-        with:
-          app-id: ${{ secrets.ENGINEER_BOT_APP_ID }}
-          private-key: ${{ secrets.ENGINEER_BOT_APP_PRIVATE_KEY }}
-
       # Python + connector deps via the repo's OWN setup-poetry action: it
       # configures poetry against the internal JFrog mirror (the protected runner
       # is egress-blocked from pypi.org), runs `poetry lock` (tolerating a stale
       # lock), and installs the connector + its deps. This is the maintained,
       # egress-safe way this repo installs itself — the agent then runs
       # `poetry run python -m pytest tests/unit` to self-verify its red→green fix.
+      # (The engineer builds/runs the connector, so unlike the reviewer it needs
+      # the deps, not just an interpreter.)
       - name: Setup Poetry + connector deps (for pytest self-verify)
         uses: ./.github/actions/setup-poetry
         with:
           python-version: '3.11'
 
-      - name: Setup Node (for the Claude Code CLI the SDK spawns)
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
-        with:
-          node-version: '20'
-
-      # PAT-free engine install: mint a SECOND token, scoped to the engine repo
-      # (contents:read), from the same engineer-bot App creds. The install step
-      # below authenticates the private-engine clone with this instead of a
-      # stored BOT_ENGINE_PAT. Requires the engineer-bot App installed on the
-      # engine repo with contents:read.
-      - name: Mint engine-scoped install token
-        id: engine-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+      # Shared prelude: mint the engineer-bot token (pushes the fix branch,
+      # comments) + the engine-scoped token, set up Node, install the pinned
+      # engine (PAT-free). `token` output is used by the steps below.
+      - name: Bot prelude (tokens + Node + engine install)
+        id: prelude
+        uses: ./.github/actions/bot-prelude
         with:
           app-id: ${{ secrets.ENGINEER_BOT_APP_ID }}
           private-key: ${{ secrets.ENGINEER_BOT_APP_PRIVATE_KEY }}
-          owner: databricks
-          repositories: databricks-bot-engine
-          permission-contents: read
+          engine-ref: b6205fb502566d617a456ccf3c37f3e4e3072ccd
 
       - name: Resolve issue + gather context
         id: ctx
@@ -108,7 +92,7 @@ jobs:
         # chosen delimiter, which would otherwise inject extra env vars). The
         # number/url are safe shapes and exported directly.
         env:
-          GH_TOKEN: ${{ steps.setup.outputs.token }}
+          GH_TOKEN: ${{ steps.prelude.outputs.token }}
           EVENT_NAME: ${{ github.event_name }}
           INPUT_ISSUE: ${{ inputs.issue_number }}
           EVENT_ISSUE: ${{ github.event.issue.number }}
@@ -131,15 +115,6 @@ jobs:
           fi
           { echo "ISSUE_TITLE<<$DELIM"; printf '%s\n' "$TITLE"; echo "$DELIM"; } >> "$GITHUB_ENV"
 
-      # Install the engine (REF mode, pinned) + Claude SDK/CLI via the LOCAL
-      # composite (cross-repo `uses:` of the engine won't resolve here),
-      # authenticated PAT-free by the engine-scoped token above.
-      - name: Install engine + Claude SDK/CLI
-        uses: ./.github/actions/install-bot-engine
-        with:
-          engine-ref: b6205fb502566d617a456ccf3c37f3e4e3072ccd
-          engine-token: ${{ steps.engine-token.outputs.token }}
-
       - name: Run author (bug-fix)
         id: author
         # Run from RUNNER_TEMP so the engine-rendered prompt's context file
@@ -168,7 +143,7 @@ jobs:
         # via the App token embedded in the remote URL (checkout ran with
         # persist-credentials: false, so this is the only push credential).
         env:
-          GH_TOKEN: ${{ steps.setup.outputs.token }}
+          GH_TOKEN: ${{ steps.prelude.outputs.token }}
           GITHUB_REPOSITORY: ${{ github.repository }}
           TEST_REPO_ROOT: ${{ github.workspace }}
           RUNNER_TEMP: ${{ runner.temp }}
@@ -190,7 +165,7 @@ jobs:
         # via --body-file so nothing reaches a shell.
         if: always() && steps.ctx.outputs.issue_number != ''
         env:
-          GH_TOKEN: ${{ steps.setup.outputs.token }}
+          GH_TOKEN: ${{ steps.prelude.outputs.token }}
           REPO: ${{ github.repository }}
           ISSUE: ${{ steps.ctx.outputs.issue_number }}
           OUTCOME: ${{ steps.author.outputs.outcome }}
diff --git a/.github/workflows/reviewer-bot-followup.yml b/.github/workflows/reviewer-bot-followup.yml
@@ -1,10 +1,10 @@
 # Reviewer Bot — follow-up on review-comment replies.
 #
-# Own-job composite caller (see reviewer-bot.yml for why we don't use the engine
-# reusable WORKFLOW: cross-repo reusable-workflow calls to the private engine
-# fail "workflow was not found"; cross-repo composite ACTIONS resolve in-org).
-# This file owns the job and replicates the reusable followup's steps with
-# cross-repo action refs, PAT-free (engine-scoped App token).
+# Own-job workflow (see reviewer-bot.yml: an external repo can't `uses:` the
+# internal engine's actions/workflows; the engine is pip-installed via the local
+# bot-prelude -> install-bot-engine composites). This file owns checkout, the
+# base-commit fetch, Setup Python, and the followup run; bot-prelude mints tokens
+# + Node + installs the engine, PAT-free.
 #
 # Enablement: no label gate — engage every non-fork open PR (this repo's policy).
 # The security floor (fork==false, PR open) is the job `if:` below; loop-
@@ -38,14 +38,6 @@ jobs:
       group: reviewer-bot-followup-pr-${{ github.event.pull_request.number }}
       cancel-in-progress: false
     steps:
-      # Review-bot token (posts inline replies + resolves threads).
-      - name: Mint review-bot App token
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
-        with:
-          app-id: ${{ secrets.REVIEW_BOT_APP_ID }}
-          private-key: ${{ secrets.REVIEW_BOT_APP_PRIVATE_KEY }}
-
       - name: Checkout PR head (read-only; agent only POSTS via GH_TOKEN)
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
@@ -71,39 +63,25 @@ jobs:
             echo "::warning::Could not fetch PR base commit ${PR_BASE_SHA}. Continuing: followup.py fail-closes to an empty SHA allowlist, so SHA verification degrades gracefully but reconciliation still runs." >&2
           fi
 
+      # Reviewer reads code, doesn't run the connector — Python interpreter only.
       - name: Setup Python
         uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
         with:
           python-version: '3.11'
 
-      - name: Setup Node (for the Claude Code CLI the SDK spawns)
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
-        with:
-          node-version: '20'
-
-      # PAT-free engine install: engine-scoped token (contents:read) from the
-      # review-bot App creds — SEPARATE from app-token above (which is scoped to
-      # THIS repo for PR posting).
-      - name: Mint engine-scoped install token
-        id: engine-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+      # Shared prelude: mint the review-bot token (posts replies / resolves
+      # threads) + the engine-scoped token, set up Node, install the engine.
+      - name: Bot prelude (tokens + Node + engine install)
+        id: prelude
+        uses: ./.github/actions/bot-prelude
         with:
           app-id: ${{ secrets.REVIEW_BOT_APP_ID }}
           private-key: ${{ secrets.REVIEW_BOT_APP_PRIVATE_KEY }}
-          owner: databricks
-          repositories: databricks-bot-engine
-          permission-contents: read
-
-      # LOCAL composite (cross-repo `uses:` of the engine won't resolve here).
-      - name: Install engine + Claude SDK/CLI
-        uses: ./.github/actions/install-bot-engine
-        with:
           engine-ref: b6205fb502566d617a456ccf3c37f3e4e3072ccd
-          engine-token: ${{ steps.engine-token.outputs.token }}
 
       - name: Run reviewer follow-up
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ steps.prelude.outputs.token }}
           GITHUB_REPOSITORY: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
           TRIGGER_COMMENT_ID: ${{ github.event.comment.id }}
diff --git a/.github/workflows/reviewer-bot.yml b/.github/workflows/reviewer-bot.yml
diff --git a/docs/superpowers/specs/2026-07-14-onboard-bot-engine-design.md b/docs/superpowers/specs/2026-07-14-onboard-bot-engine-design.md
