diff --git a/play.ts b/play.ts
index 068f417..613d8e3 100644
--- a/play.ts
+++ b/play.ts
@@ -10,6 +10,7 @@ import { type Inputs, main } from "./main.ts";
 import { defineFixture } from "./test/utils.ts";
 import { log } from "./utils/cli.ts";
 import { runInDocker } from "./utils/docker.ts";
+import { ensureGitHubToken } from "./utils/github.ts";
 import { isInsideDocker } from "./utils/globals.ts";
 import { setupTestRepo } from "./utils/setup.ts";
 
@@ -34,6 +35,8 @@ config();
 config({ path: join(__dirname, "..", ".env") });
 
 export async function run(inputsOrPrompt: Inputs | string): Promise<AgentResult> {
+  await ensureGitHubToken();
+
   // create unique temp directory path in OS temp location for parallel execution
   // use a parent dir from mkdtemp, then clone into a 'repo' subdirectory
   const tempParent = await mkdtemp(join(tmpdir(), "pullfrog-play-"));
diff --git a/test/run.ts b/test/run.ts
index 90524d6..da22f4f 100644
--- a/test/run.ts
+++ b/test/run.ts
@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { config } from "dotenv";
 import { runInDocker } from "../utils/docker.ts";
-import { acquireNewToken } from "../utils/github.ts";
+import { ensureGitHubToken } from "../utils/github.ts";
 import { isInsideDocker } from "../utils/globals.ts";
 import {
   installSignalHandlers,
@@ -388,13 +388,7 @@ async function main(): Promise<void> {
   // run in Docker unless already inside
   if (!isInsideDocker) {
     // acquire token for docker if needed
-    if (!process.env.GITHUB_TOKEN && !process.env.GH_TOKEN) {
-      if (process.env.GITHUB_APP_ID && process.env.GITHUB_PRIVATE_KEY) {
-        console.log("» acquiring github installation token...");
-        const token = await acquireNewToken();
-        process.env.GITHUB_TOKEN = token;
-      }
-    }
+    await ensureGitHubToken();
     runTestsInDocker(args);
   }
 
diff --git a/utils/github.ts b/utils/github.ts
index ded0116..14b094a 100644
--- a/utils/github.ts
+++ b/utils/github.ts
@@ -274,6 +274,24 @@ async function acquireTokenViaGitHubApp(opts?: AcquireTokenOptions): Promise<str
   return await createInstallationToken(jwt, installationId, opts?.permissions);
 }
 
+/**
+ * Ensure a GitHub token is available in the environment.
+ *
+ * If neither `GITHUB_TOKEN` nor `GH_TOKEN` is set, attempts to acquire an
+ * installation token using `GITHUB_APP_ID` / `GITHUB_PRIVATE_KEY`.
+ *
+ * **Not intended for production use** — this is a convenience for local
+ * development and test harnesses where tokens aren't pre-provisioned.
+ */
+export async function ensureGitHubToken(): Promise<void> {
+  if (!process.env.GITHUB_TOKEN && !process.env.GH_TOKEN) {
+    if (process.env.GITHUB_APP_ID && process.env.GITHUB_PRIVATE_KEY) {
+      const token = await acquireNewToken();
+      process.env.GITHUB_TOKEN = token;
+    }
+  }
+}
+
 export async function acquireNewToken(opts?: AcquireTokenOptions): Promise<string> {
   if (isOIDCAvailable()) {
     return await retry(() => acquireTokenViaOIDC(opts), {