Add read-only Dependabot decision previews

Run read-only planning on pushes to cklin/dependabot-automation using
the pushed commit. Share evaluation decisions with the live controller
and summarize intended actions without changing PRs or rerunning CI.

Keep live processing off push events and restrict the planning job to
read permissions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d63bcb34-3969-4d14-b422-33728176ec03

Author: cklin

.github/dependabot-automation/README.md

@@ -33,6 +33,21 @@ State crosses invocations through:
 - **Artifacts:** evidence goes to the worker; its repair or diagnosis goes to the
   trusted publisher.
 
+## Temporary branch-push dry run
+
+Pushes to `cklin/dependabot-automation` run a read-only preview using the pushed
+commit, not `main`. The `dry-run` job summary lists selected PRs, their heads,
+planned actions and reasons, native auto-merge disarming, and retry run IDs.
+Discovery and evaluation use the same decision logic as live processing.
+
+The preview token has only contents, pull-request, and Actions read permissions.
+It does not change PRs, rerun CI, collect investigation artifacts, mint App tokens,
+or invoke Copilot. Live jobs are excluded from push events and still load trusted
+code from `main` for their existing triggers. The preview does not validate merge
+authorization or Copilot repair outcomes.
+
+This preparation is kept in a separate commit so it can be dropped after testing.
+
 ## Lifecycle
 
 ```text
@@ -75,6 +90,7 @@ to diagnose the blocker. Other merge API errors fail the run.
 | File                  | Responsibility                                                                                |
 | --------------------- | --------------------------------------------------------------------------------------------- |
 | `controller.cjs`      | Workflow commands, eligibility, transitions, and trusted GitHub writes.                       |
+| `dry-run.cjs`         | Read-only branch-push preview and job summary, using the controller's shared planner.         |
 | `evidence.cjs`        | Collect PR text, patches, failed-job logs, and their index.                                   |
 | `repair-protocol.cjs` | Validate result shape, allowed repair paths, and size limits. Shared by worker and publisher. |
 | `worker.cjs`          | Invoke Copilot and collect actual checkout changes, not model-supplied file contents.         |

.github/dependabot-automation/controller.cjs

@@ -27,6 +27,7 @@ function createController({
   const repository = `${repo.owner}/${repo.repo}`;
   return {
     discover,
+    plan,
     evaluate,
     retry,
     approve,
@@ -64,42 +65,52 @@ function createController({
     );
     core.setOutput("prs", JSON.stringify(selected.map((pr) => pr.number)));
     core.setOutput("has-prs", selected.length > 0);
+    return selected.map((pr) => pr.number);
+  }
+
+  async function plan() {
+    const pr = await getPr();
+    return {
+      pr,
+      disableAutoMerge: isCandidate(pr, repository) && Boolean(pr.auto_merge),
+      ...(await planPr(pr)),
+    };
   }
 
   async function evaluate() {
     const pr = await getPr();
     if (!isCandidate(pr, repository)) return;
     // Do not leave native auto-merge armed while diagnosis can change PR state.
     await disableAutoMerge(pr);
-    if (hasAutomationHold(pr)) return;
-    if (!(await hasPristineHistory(pr))) {
-      await requireHumanReview(
-        "This PR contains commits other than verified Dependabot changes.",
-      );
-      return;
-    }
-    const { runs, state } = await readCiState(pr.head.sha);
-    core.info(`PR #${number} at ${pr.head.sha}: ${state}`);
-    if (state === "waiting") return;
-    core.setOutput("head", pr.head.sha);
-    if (state === "passing") {
-      core.setOutput("action", "merge");
-      return;
-    }
-    if (canRetry(runs.filter((run) => run.conclusion !== "success"))) {
-      core.setOutput("action", "retry");
-      return;
+    const decision = await planPr(pr);
+    switch (decision.action) {
+      case "skip":
+      case "wait":
+        return;
+      case "needs-review":
+        await requireHumanReview(decision.reason);
+        return;
+      case "merge":
+      case "retry":
+        core.setOutput("head", pr.head.sha);
+        core.setOutput("action", decision.action);
+        return;
+      case "investigate":
+        core.setOutput("head", pr.head.sha);
+        // Entering Copilot is a one-way merge handoff, even if it makes no edits.
+        await addLabel(reviewLabel);
+        await writeInvestigation({
+          github,
+          repo,
+          pr,
+          runs: decision.runs,
+          outputDir: path.join(workspace, "investigation"),
+        });
+        core.setOutput("action", "investigate");
+        return;
+      default:
+        throw new Error(`Unsupported evaluation action: ${decision.action}`);
     }
-    // Entering Copilot is a one-way merge handoff, even if it makes no edits.
-    await addLabel(reviewLabel);
-    await writeInvestigation({
-      github,
-      repo,
-      pr,
-      runs,
-      outputDir: path.join(workspace, "investigation"),
-    });
-    core.setOutput("action", "investigate");
   }
 
   async function retry() {
@@ -210,6 +221,57 @@ function createController({
     );
   }
 
+  async function planPr(pr) {
+    if (!isCandidate(pr, repository)) {
+      return {
+        action: "skip",
+        reason: "PR is no longer an eligible Dependabot update.",
+      };
+    }
+    if (hasAutomationHold(pr)) {
+      return {
+        action: "skip",
+        reason: "An automation hold requires a maintainer decision.",
+      };
+    }
+    if (!(await hasPristineHistory(pr))) {
+      return {
+        action: "needs-review",
+        reason:
+          "This PR contains commits other than verified Dependabot changes.",
+      };
+    }
+    const { runs, state } = await readCiState(pr.head.sha);
+    core.info(`PR #${number} at ${pr.head.sha}: ${state}`);
+    if (state === "waiting") {
+      return {
+        action: "wait",
+        reason: "Configured PR CI workflows are missing or still running.",
+      };
+    }
+    if (state === "passing") {
+      return {
+        action: "merge",
+        reason:
+          "Verified Dependabot-only history; all configured PR CI workflows passed.",
+      };
+    }
+    const failed = runs.filter((run) => run.conclusion !== "success");
+    if (canRetry(failed)) {
+      return {
+        action: "retry",
+        reason:
+          "All failed configured workflows qualify for their first retry.",
+        runs: failed,
+      };
+    }
+    return {
+      action: "investigate",
+      reason: "CI failed and is not eligible for an automatic retry.",
+      runs,
+    };
+  }
+
   async function requireExpectedPr() {
     const pr = await getPr();
     if (!isCandidate(pr, repository) || pr.head.sha !== expectedSha) {

.github/dependabot-automation/controller.test.cjs

@@ -16,6 +16,7 @@ const {
 const { writeInvestigation } = require("./evidence.cjs");
 const { allowedFile, validateResult } = require("./repair-protocol.cjs");
 const { collectFiles, run } = require("./worker.cjs");
+const { dryRun } = require("./dry-run.cjs");
 
 const head = "a".repeat(40);
 const repo = { owner: "github", repo: "vscode-codeql" };
@@ -258,6 +259,143 @@ test("discovery randomly selects bounded batches without replacement", async (t)
   }
 });
 
+test("planning reports live decisions without mutations or evidence collection", async (t) => {
+  for (const [name, change, action] of [
+    [
+      "ineligible",
+      (state) => {
+        state.pr.draft = true;
+      },
+      "skip",
+    ],
+    [
+      "held",
+      (state) => {
+        state.pr.labels.push({ name: reviewLabel });
+      },
+      "skip",
+    ],
+    [
+      "non-pristine",
+      (state) => {
+        state.commits[0].author.login = "someone";
+      },
+      "needs-review",
+    ],
+    [
+      "waiting",
+      (state) => {
+        state.runs.pop();
+      },
+      "wait",
+    ],
+    ["passing", () => {}, "merge"],
+    [
+      "retryable",
+      (state) => {
+        state.runs[0].conclusion = "failure";
+        state.runs[2].conclusion = "timed_out";
+      },
+      "retry",
+    ],
+    [
+      "investigation",
+      (state) => {
+        state.runs[0].conclusion = "failure";
+        state.runs[0].run_attempt = 2;
+      },
+      "investigate",
+    ],
+  ]) {
+    await t.test(name, async (t) => {
+      const workspace = temporaryWorkspace(t);
+      const { controller, state } = harness({ workspace });
+      state.pr.auto_merge = {};
+      change(state);
+      const originalPr = structuredClone(state.pr);
+      const decision = await controller.plan();
+      assert.equal(decision.action, action);
+      assert.equal(decision.pr.head.sha, head);
+      assert(decision.reason);
+      assert.equal(decision.disableAutoMerge, name !== "ineligible");
+      if (action === "retry") {
+        assert.deepEqual(
+          decision.runs.map((run) => run.id),
+          [1, 3],
+        );
+      }
+      assert.deepEqual(state.pr, originalPr);
+      assert.deepEqual(state.calls, []);
+      assert.deepEqual(state.comments, []);
+      assert.deepEqual(state.outputs, {});
+      assert.deepEqual(fs.readdirSync(workspace), []);
+    });
+  }
+});
+
+test("planning propagates unavailable CI instead of reporting a decision", async () => {
+  const { controller, github, state } = harness();
+  github.rest.actions.listWorkflowRunsForRepo = async () => {
+    throw new Error("Cannot read CI");
+  };
+  await assert.rejects(controller.plan(), /Cannot read CI/);
+  assert.deepEqual(state.calls, []);
+  assert.deepEqual(state.outputs, {});
+});
+
+test("dry-run orchestration reports investigation using only read APIs", async () => {
+  const { state, github } = harness();
+  state.pr.auto_merge = {};
+  state.runs[0].conclusion = "failure";
+  state.runs[0].run_attempt = 2;
+  const readOnlyGithub = {
+    rest: {
+      pulls: {
+        list: github.rest.pulls.list,
+        get: github.rest.pulls.get,
+        listCommits: github.rest.pulls.listCommits,
+      },
+      actions: {
+        listWorkflowRunsForRepo: github.rest.actions.listWorkflowRunsForRepo,
+      },
+    },
+    paginate: github.paginate,
+  };
+  const content = [];
+  let written = false;
+  const summary = {
+    addHeading(text) {
+      content.push(text);
+      return this;
+    },
+    addRaw(text) {
+      content.push(text);
+      return this;
+    },
+    addTable(rows) {
+      content.push(...rows.flat().filter((cell) => typeof cell === "string"));
+      return this;
+    },
+    async write() {
+      written = true;
+    },
+  };
+  await dryRun({
+    github: readOnlyGithub,
+    context: { repo },
+    core: { info() {}, setOutput() {}, summary },
+  });
+  assert(written);
+  const report = content.join("\n");
+  assert.match(report, /#42/);
+  assert(report.includes(head));
+  assert.match(report, /Add review hold, collect evidence, and invoke Copilot/);
+  assert.match(report, /Read-only preview/);
+  assert.match(report, /not validated/);
+  assert.deepEqual(state.calls, []);
+  assert.deepEqual(state.pr.labels, []);
+});
+
 test("only open, non-draft, same-repository Dependabot PRs qualify", () => {
   const pr = candidate();
   assert(isCandidate(pr, "github/vscode-codeql"));

.github/dependabot-automation/dry-run.cjs

@@ -0,0 +1,53 @@
+const { createController } = require("./controller.cjs");
+
+async function dryRun({ github, context, core }) {
+  const numbers = await createController({ github, context, core }).discover();
+  const actions = {
+    skip: "Skip",
+    wait: "Wait for CI",
+    "needs-review": "Add review hold and post explanation",
+    merge: "Approve if needed and attempt merge",
+    retry: "Comment and rerun failed jobs once",
+    investigate: "Add review hold, collect evidence, and invoke Copilot",
+  };
+  const rows = [
+    [
+      "PR",
+      "Head",
+      "Planned action",
+      "Reason",
+      "Disable auto-merge",
+      "Retry runs",
+    ].map((data) => ({ data, header: true })),
+  ];
+  for (const number of numbers) {
+    const decision = await createController({
+      github,
+      context,
+      core,
+      number,
+    }).plan();
+    rows.push([
+      `#${number}`,
+      decision.pr.head.sha,
+      actions[decision.action],
+      decision.reason,
+      decision.disableAutoMerge ? "Yes" : "No",
+      decision.action === "retry"
+        ? decision.runs.map((run) => run.id).join(", ")
+        : "",
+    ]);
+  }
+  await core.summary
+    .addHeading("Dependabot automation dry run")
+    .addRaw(
+      "Read-only preview: no PR changes, CI reruns, App tokens, or Copilot invocation. " +
+        "Merge success and repair outcomes are not validated.",
+      true,
+    )
+    .addRaw(`Selected ${numbers.length} PRs.`, true)
+    .addTable(rows)
+    .write();
+}
+
+module.exports = { dryRun };