feat: initial import of experimental GitHub Action (#1170)

This is a first cut at a GitHub Action that lets you define prompt
templates in `.md` files under `.github/codex/labels` that will run
Codex with the associated prompt when the label is added to a GitHub
pull request.

For example, this PR includes these files:

```
.github/codex/labels/codex-attempt.md
.github/codex/labels/codex-code-review.md
.github/codex/labels/codex-investigate-issue.md
```

And the new `.github/workflows/codex.yml` workflow declares the
following triggers:

```yaml
on:
  issues:
    types: [opened, labeled]
  pull_request:
    branches: [main]
    types: [labeled]
```

as well as the following expression to gate the action:

```
jobs:
  codex:
    if: |
      (github.event_name == 'issues' && (
        (github.event.action == 'labeled' && (github.event.label.name == 'codex-attempt' || github.event.label.name == 'codex-investigate-issue'))
      )) ||
      (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'codex-code-review')
```

Note the "actor" who added the label must have write access to the repo
for the action to take effect.

After adding a label, the action will "ack" the request by replacing the
original label (e.g., `codex-review`) with an `-in-progress` suffix
(e.g., `codex-review-in-progress`). When it is finished, it will swap
the `-in-progress` label with a `-completed` one (e.g.,
`codex-review-completed`).

Users of the action are responsible for providing an `OPENAI_API_KEY`
and making it available as a secret to the action.

.github/actions/codex/src/add-reaction.ts

@@ -0,0 +1,85 @@
+import * as github from "@actions/github";
+import type { EnvContext } from "./env-context";
+
+/**
+ * Add an "eyes" reaction to the entity (issue, issue comment, or pull request
+ * review comment) that triggered the current Codex invocation.
+ *
+ * The purpose is to provide immediate feedback to the user – similar to the
+ * *-in-progress label flow – indicating that the bot has acknowledged the
+ * request and is working on it.
+ *
+ * We attempt to add the reaction best suited for the current GitHub event:
+ *
+ *   • issues              → POST /repos/{owner}/{repo}/issues/{issue_number}/reactions
+ *   • issue_comment       → POST /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions
+ *   • pull_request_review_comment → POST /repos/{owner}/{repo}/pulls/comments/{comment_id}/reactions
+ *
+ * If the specific target is unavailable (e.g. unexpected payload shape) we
+ * silently skip instead of failing the whole action because the reaction is
+ * merely cosmetic.
+ */
+export async function addEyesReaction(ctx: EnvContext): Promise<void> {
+  const octokit = ctx.getOctokit();
+  const { owner, repo } = github.context.repo;
+  const eventName = github.context.eventName;
+
+  try {
+    switch (eventName) {
+      case "issue_comment": {
+        const commentId = (github.context.payload as any)?.comment?.id;
+        if (commentId) {
+          await octokit.rest.reactions.createForIssueComment({
+            owner,
+            repo,
+            comment_id: commentId,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      case "pull_request_review_comment": {
+        const commentId = (github.context.payload as any)?.comment?.id;
+        if (commentId) {
+          await octokit.rest.reactions.createForPullRequestReviewComment({
+            owner,
+            repo,
+            comment_id: commentId,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      case "issues": {
+        const issueNumber = github.context.issue.number;
+        if (issueNumber) {
+          await octokit.rest.reactions.createForIssue({
+            owner,
+            repo,
+            issue_number: issueNumber,
+            content: "eyes",
+          });
+          return;
+        }
+        break;
+      }
+      default: {
+        // Fallback: try to react to the issue/PR if we have a number.
+        const issueNumber = github.context.issue.number;
+        if (issueNumber) {
+          await octokit.rest.reactions.createForIssue({
+            owner,
+            repo,
+            issue_number: issueNumber,
+            content: "eyes",
+          });
+        }
+      }
+    }
+  } catch (error) {
+    // Do not fail the action if reaction creation fails – log and continue.
+    console.warn(`Failed to add \"eyes\" reaction: ${error}`);
+  }
+}

.github/actions/codex/src/comment.ts

@@ -0,0 +1,53 @@
+import type { EnvContext } from "./env-context";
+import { runCodex } from "./run-codex";
+import { postComment } from "./post-comment";
+import { addEyesReaction } from "./add-reaction";
+
+/**
+ * Handle `issue_comment` and `pull_request_review_comment` events once we know
+ * the action is supported.
+ */
+export async function onComment(ctx: EnvContext): Promise<void> {
+  const triggerPhrase = ctx.tryGet("INPUT_TRIGGER_PHRASE");
+  if (!triggerPhrase) {
+    console.warn("Empty trigger phrase: skipping.");
+    return;
+  }
+
+  // Attempt to get the body of the comment from the environment. Depending on
+  // the event type either `GITHUB_EVENT_COMMENT_BODY` (issue & PR comments) or
+  // `GITHUB_EVENT_REVIEW_BODY` (PR reviews) is set.
+  const commentBody =
+    ctx.tryGetNonEmpty("GITHUB_EVENT_COMMENT_BODY") ??
+    ctx.tryGetNonEmpty("GITHUB_EVENT_REVIEW_BODY") ??
+    ctx.tryGetNonEmpty("GITHUB_EVENT_ISSUE_BODY");
+
+  if (!commentBody) {
+    console.warn("Comment body not found in environment: skipping.");
+    return;
+  }
+
+  // Check if the trigger phrase is present.
+  if (!commentBody.includes(triggerPhrase)) {
+    console.log(
+      `Trigger phrase '${triggerPhrase}' not found: nothing to do for this comment.`,
+    );
+    return;
+  }
+
+  // Derive the prompt by removing the trigger phrase. Remove only the first
+  // occurrence to keep any additional occurrences that might be meaningful.
+  const prompt = commentBody.replace(triggerPhrase, "").trim();
+
+  if (prompt.length === 0) {
+    console.warn("Prompt is empty after removing trigger phrase: skipping");
+    return;
+  }
+
+  // Provide immediate feedback that we are working on the request.
+  await addEyesReaction(ctx);
+
+  // Run Codex and post the response as a new comment.
+  const lastMessage = await runCodex(prompt, ctx);
+  await postComment(lastMessage, ctx);
+}

.github/actions/codex/src/config.ts

@@ -0,0 +1,11 @@
+import { readdirSync, statSync } from "fs";
+import * as path from "path";
+
+export interface Config {
+  labels: Record<string, LabelConfig>;
+}
+
+export interface LabelConfig {
+  /** Returns the prompt template. */
+  getPromptTemplate(): string;
+}

.github/actions/codex/src/default-label-config.ts

@@ -0,0 +1,44 @@
+import type { Config } from "./config";
+
+export function getDefaultConfig(): Config {
+  return {
+    labels: {
+      "codex-investigate-issue": {
+        getPromptTemplate: () =>
+          `
+Troubleshoot whether the reported issue is valid.
+
+Provide a concise and respectful comment summarizing the findings.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}
+`.trim(),
+      },
+      "codex-code-review": {
+        getPromptTemplate: () =>
+          `
+Review this PR and respond with a very concise final message, formatted in Markdown.
+
+There should be a summary of the changes (1-2 sentences) and a few bullet points if necessary.
+
+Then provide the **review** (1-2 sentences plus bullet points, friendly tone).
+
+{CODEX_ACTION_GITHUB_EVENT_PATH} contains the JSON that triggered this GitHub workflow. It contains the \`base\` and \`head\` refs that define this PR. Both refs are available locally.
+`.trim(),
+      },
+      "codex-attempt-fix": {
+        getPromptTemplate: () =>
+          `
+Attempt to solve the reported issue.
+
+If a code change is required, create a new branch, commit the fix, and open a pull-request that resolves the problem.
+
+### {CODEX_ACTION_ISSUE_TITLE}
+
+{CODEX_ACTION_ISSUE_BODY}
+`.trim(),
+      },
+    },
+  };
+}

.github/actions/codex/src/env-context.ts

@@ -0,0 +1,116 @@
+/*
+ * Centralised access to environment variables used by the Codex GitHub
+ * Action.
+ *
+ * To enable proper unit-testing we avoid reading from `process.env` at module
+ * initialisation time.  Instead a `EnvContext` object is created (usually from
+ * the real `process.env`) and passed around explicitly or – where that is not
+ * yet practical – imported as the shared `defaultContext` singleton. Tests can
+ * create their own context backed by a stubbed map of variables without having
+ * to mutate global state.
+ */
+
+import { fail } from "./fail";
+import * as github from "@actions/github";
+
+export interface EnvContext {
+  /**
+   * Return the value for a given environment variable or terminate the action
+   * via `fail` if it is missing / empty.
+   */
+  get(name: string): string;
+
+  /**
+   * Attempt to read an environment variable. Returns the value when present;
+   * otherwise returns undefined (does not call `fail`).
+   */
+  tryGet(name: string): string | undefined;
+
+  /**
+   * Attempt to read an environment variable. Returns non-empty string value or
+   * null if unset or empty string.
+   */
+  tryGetNonEmpty(name: string): string | null;
+
+  /**
+   * Return a memoised Octokit instance authenticated via the token resolved
+   * from the provided argument (when defined) or the environment variables
+   * `GITHUB_TOKEN`/`GH_TOKEN`.
+   *
+   * Subsequent calls return the same cached instance to avoid spawning
+   * multiple REST clients within a single action run.
+   */
+  getOctokit(token?: string): ReturnType<typeof github.getOctokit>;
+}
+
+/** Internal helper – *not* exported. */
+function _getRequiredEnv(
+  name: string,
+  env: Record<string, string | undefined>,
+): string | undefined {
+  const value = env[name];
+
+  // Avoid leaking secrets into logs while still logging non-secret variables.
+  if (name.endsWith("KEY") || name.endsWith("TOKEN")) {
+    if (value) {
+      console.log(`value for ${name} was found`);
+    }
+  } else {
+    console.log(`${name}=${value}`);
+  }
+
+  return value;
+}
+
+/** Create a context backed by the supplied environment map (defaults to `process.env`). */
+export function createEnvContext(
+  env: Record<string, string | undefined> = process.env,
+): EnvContext {
+  // Lazily instantiated Octokit client – shared across this context.
+  let cachedOctokit: ReturnType<typeof github.getOctokit> | null = null;
+
+  return {
+    get(name: string): string {
+      const value = _getRequiredEnv(name, env);
+      if (value == null) {
+        fail(`Missing required environment variable: ${name}`);
+      }
+      return value;
+    },
+
+    tryGet(name: string): string | undefined {
+      return _getRequiredEnv(name, env);
+    },
+
+    tryGetNonEmpty(name: string): string | null {
+      const value = _getRequiredEnv(name, env);
+      return value == null || value === "" ? null : value;
+    },
+
+    getOctokit(token?: string) {
+      if (cachedOctokit) {
+        return cachedOctokit;
+      }
+
+      // Determine the token to authenticate with.
+      const githubToken = token ?? env["GITHUB_TOKEN"] ?? env["GH_TOKEN"];
+
+      if (!githubToken) {
+        fail(
+          "Unable to locate a GitHub token. `github_token` should have been set on the action.",
+        );
+      }
+
+      cachedOctokit = github.getOctokit(githubToken!);
+      return cachedOctokit;
+    },
+  };
+}
+
+/**
+ * Shared context built from the actual `process.env`.  Production code that is
+ * not yet refactored to receive a context explicitly may import and use this
+ * singleton.  Tests should avoid the singleton and instead pass their own
+ * context to the functions they exercise.
+ */
+export const defaultContext: EnvContext = createEnvContext();

.github/actions/codex/src/fail.ts

@@ -0,0 +1,4 @@
+export function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}

.github/actions/codex/src/git-helpers.ts

@@ -0,0 +1,149 @@
+import { spawnSync } from "child_process";
+import * as github from "@actions/github";
+import { EnvContext } from "./env-context";
+
+function runGit(args: string[], silent = true): string {
+  console.info(`Running git ${args.join(" ")}`);
+  const res = spawnSync("git", args, {
+    encoding: "utf8",
+    stdio: silent ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+  if (res.error) {
+    throw res.error;
+  }
+  if (res.status !== 0) {
+    // Return stderr so caller may handle; else throw.
+    throw new Error(
+      `git ${args.join(" ")} failed with code ${res.status}: ${res.stderr}`,
+    );
+  }
+  return res.stdout.trim();
+}
+
+function stageAllChanges() {
+  runGit(["add", "-A"]);
+}
+
+function hasStagedChanges(): boolean {
+  const res = spawnSync("git", ["diff", "--cached", "--quiet", "--exit-code"]);
+  return res.status !== 0;
+}
+
+function ensureOnBranch(
+  issueNumber: number,
+  protectedBranches: string[],
+  suggestedSlug?: string,
+): string {
+  let branch = "";
+  try {
+    branch = runGit(["symbolic-ref", "--short", "-q", "HEAD"]);
+  } catch {
+    branch = "";
+  }
+
+  // If detached HEAD or on a protected branch, create a new branch.
+  if (!branch || protectedBranches.includes(branch)) {
+    if (suggestedSlug) {
+      const safeSlug = suggestedSlug
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+      branch = `codex-fix-${issueNumber}-${safeSlug}`;
+    } else {
+      branch = `codex-fix-${issueNumber}-${Date.now()}`;
+    }
+    runGit(["switch", "-c", branch]);
+  }
+  return branch;
+}
+
+function commitIfNeeded(issueNumber: number) {
+  if (hasStagedChanges()) {
+    runGit([
+      "commit",
+      "-m",
+      `fix: automated fix for #${issueNumber} via Codex`,
+    ]);
+  }
+}
+
+function pushBranch(branch: string, githubToken: string, ctx: EnvContext) {
+  const repoSlug = ctx.get("GITHUB_REPOSITORY"); // owner/repo
+  const remoteUrl = `https://x-access-token:${githubToken}@github.com/${repoSlug}.git`;
+
+  runGit(["push", "--force-with-lease", "-u", remoteUrl, `HEAD:${branch}`]);
+}
+
+/**
+ * If this returns a string, it is the URL of the created PR.
+ */
+export async function maybePublishPRForIssue(
+  issueNumber: number,
+  lastMessage: string,
+  ctx: EnvContext,
+): Promise<string | undefined> {
+  // Only proceed if GITHUB_TOKEN available.
+  const githubToken =
+    ctx.tryGetNonEmpty("GITHUB_TOKEN") ?? ctx.tryGetNonEmpty("GH_TOKEN");
+  if (!githubToken) {
+    console.warn("No GitHub token - skipping PR creation.");
+    return undefined;
+  }
+
+  // Print `git status` for debugging.
+  runGit(["status"]);
+
+  // Stage any remaining changes so they can be committed and pushed.
+  stageAllChanges();
+
+  const octokit = ctx.getOctokit(githubToken);
+
+  const { owner, repo } = github.context.repo;
+
+  // Determine default branch to treat as protected.
+  let defaultBranch = "main";
+  try {
+    const repoInfo = await octokit.rest.repos.get({ owner, repo });
+    defaultBranch = repoInfo.data.default_branch ?? "main";
+  } catch (e) {
+    console.warn(`Failed to get default branch, assuming 'main': ${e}`);
+  }
+
+  const sanitizedMessage = lastMessage.replace(/\u2022/g, "-");
+  const [summaryLine] = sanitizedMessage.split(/\r?\n/);
+  const branch = ensureOnBranch(issueNumber, [defaultBranch, "master"], summaryLine);
+  commitIfNeeded(issueNumber);
+  pushBranch(branch, githubToken, ctx);
+
+  // Try to find existing PR for this branch
+  const headParam = `${owner}:${branch}`;
+  const existing = await octokit.rest.pulls.list({
+    owner,
+    repo,
+    head: headParam,
+    state: "open",
+  });
+  if (existing.data.length > 0) {
+    return existing.data[0].html_url;
+  }
+
+  // Determine base branch (default to main)
+  let baseBranch = "main";
+  try {
+    const repoInfo = await octokit.rest.repos.get({ owner, repo });
+    baseBranch = repoInfo.data.default_branch ?? "main";
+  } catch (e) {
+    console.warn(`Failed to get default branch, assuming 'main': ${e}`);
+  }
+
+  const pr = await octokit.rest.pulls.create({
+    owner,
+    repo,
+    title: summaryLine,
+    head: branch,
+    base: baseBranch,
+    body: sanitizedMessage,
+  });
+  return pr.data.html_url;
+}

.github/actions/codex/src/git-user.ts

@@ -0,0 +1,16 @@
+export function setGitHubActionsUser(): void {
+  const commands = [
+    ["git", "config", "--global", "user.name", "github-actions[bot]"],
+    [
+      "git",
+      "config",
+      "--global",
+      "user.email",
+      "41898282+github-actions[bot]@users.noreply.github.com",
+    ],
+  ];
+
+  for (const command of commands) {
+    Bun.spawnSync(command);
+  }
+}

.github/actions/codex/src/github-workspace.ts

@@ -0,0 +1,11 @@
+import * as pathMod from "path";
+import { EnvContext } from "./env-context";
+
+export function resolveWorkspacePath(path: string, ctx: EnvContext): string {
+  if (pathMod.isAbsolute(path)) {
+    return path;
+  } else {
+    const workspace = ctx.get("GITHUB_WORKSPACE");
+    return pathMod.join(workspace, path);
+  }
+}

.github/actions/codex/src/load-config.ts

@@ -0,0 +1,56 @@
+import type { Config, LabelConfig } from "./config";
+
+import { getDefaultConfig } from "./default-label-config";
+import { readFileSync, readdirSync, statSync } from "fs";
+import * as path from "path";
+
+/**
+ * Build an in-memory configuration object by scanning the repository for
+ * Markdown templates located in `.github/codex/labels`.
+ *
+ * Each `*.md` file in that directory represents a label that can trigger the
+ * Codex GitHub Action. The filename **without** the extension is interpreted
+ * as the label name, e.g. `codex-review.md` ➜ `codex-review`.
+ *
+ * For every such label we derive the corresponding `doneLabel` by appending
+ * the suffix `-completed`.
+ */
+export function loadConfig(workspace: string): Config {
+  const labelsDir = path.join(workspace, ".github", "codex", "labels");
+
+  let entries: string[];
+  try {
+    entries = readdirSync(labelsDir);
+  } catch {
+    // If the directory is missing, return the default configuration.
+    return getDefaultConfig();
+  }
+
+  const labels: Record<string, LabelConfig> = {};
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) {
+      continue;
+    }
+
+    const fullPath = path.join(labelsDir, entry);
+
+    if (!statSync(fullPath).isFile()) {
+      continue;
+    }
+
+    const labelName = entry.slice(0, -3); // trim ".md"
+
+    labels[labelName] = new FileLabelConfig(fullPath);
+  }
+
+  return { labels };
+}
+
+class FileLabelConfig implements LabelConfig {
+  constructor(private readonly promptPath: string) {}
+
+  getPromptTemplate(): string {
+    return readFileSync(this.promptPath, "utf8");
+  }
+}

.github/actions/codex/src/main.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env bun
+
+import type { Config } from "./config";
+
+import { defaultContext, EnvContext } from "./env-context";
+import { loadConfig } from "./load-config";
+import { setGitHubActionsUser } from "./git-user";
+import { onLabeled } from "./process-label";
+import { ensureBaseAndHeadCommitsForPRAreAvailable } from "./prompt-template";
+import { performAdditionalValidation } from "./verify-inputs";
+import { onComment } from "./comment";
+import { onReview } from "./review";
+
+async function main(): Promise<void> {
+  const ctx: EnvContext = defaultContext;
+
+  // Build the configuration dynamically by scanning `.github/codex/labels`.
+  const GITHUB_WORKSPACE = ctx.get("GITHUB_WORKSPACE");
+  const config: Config = loadConfig(GITHUB_WORKSPACE);
+
+  // Optionally perform additional validation of prompt template files.
+  performAdditionalValidation(config, GITHUB_WORKSPACE);
+
+  const GITHUB_EVENT_NAME = ctx.get("GITHUB_EVENT_NAME");
+  const GITHUB_EVENT_ACTION = ctx.get("GITHUB_EVENT_ACTION");
+
+  // Set user.name and user.email to a bot before Codex runs, just in case it
+  // creates a commit.
+  setGitHubActionsUser();
+
+  switch (GITHUB_EVENT_NAME) {
+    case "issues": {
+      if (GITHUB_EVENT_ACTION === "labeled") {
+        await onLabeled(config, ctx);
+        return;
+      } else if (GITHUB_EVENT_ACTION === "opened") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+    case "issue_comment": {
+      if (GITHUB_EVENT_ACTION === "created") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request": {
+      if (GITHUB_EVENT_ACTION === "labeled") {
+        await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+        await onLabeled(config, ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request_review": {
+      await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+      if (GITHUB_EVENT_ACTION === "submitted") {
+        await onReview(ctx);
+        return;
+      }
+      break;
+    }
+    case "pull_request_review_comment": {
+      await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+      if (GITHUB_EVENT_ACTION === "created") {
+        await onComment(ctx);
+        return;
+      }
+      break;
+    }
+  }
+
+  console.warn(
+    `Unsupported action '${GITHUB_EVENT_ACTION}' for event '${GITHUB_EVENT_NAME}'.`,
+  );
+}
+
+main();

.github/actions/codex/src/post-comment.ts

@@ -0,0 +1,60 @@
+import { fail } from "./fail";
+import * as github from "@actions/github";
+import { EnvContext } from "./env-context";
+
+/**
+ * Post a comment to the issue / pull request currently in scope.
+ *
+ * Provide the environment context so that token lookup (inside getOctokit) does
+ * not rely on global state.
+ */
+export async function postComment(
+  commentBody: string,
+  ctx: EnvContext,
+): Promise<void> {
+  // Append a footer with a link back to the workflow run, if available.
+  const footer = buildWorkflowRunFooter(ctx);
+  const bodyWithFooter = footer ? `${commentBody}${footer}` : commentBody;
+
+  const octokit = ctx.getOctokit();
+  const { owner, repo } = github.context.repo;
+  const issueNumber = github.context.issue.number;
+
+  if (!issueNumber) {
+    console.warn(
+      "No issue or pull_request number found in GitHub context; skipping comment creation.",
+    );
+    return;
+  }
+
+  try {
+    await octokit.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number: issueNumber,
+      body: bodyWithFooter,
+    });
+  } catch (error) {
+    fail(`Failed to create comment via GitHub API: ${error}`);
+  }
+}
+
+/**
+ * Helper to build a Markdown fragment linking back to the workflow run that
+ * generated the current comment. Returns `undefined` if required environment
+ * variables are missing – e.g. when running outside of GitHub Actions – so we
+ * can gracefully skip the footer in those cases.
+ */
+function buildWorkflowRunFooter(ctx: EnvContext): string | undefined {
+  const serverUrl =
+    ctx.tryGetNonEmpty("GITHUB_SERVER_URL") ?? "https://github.com";
+  const repository = ctx.tryGetNonEmpty("GITHUB_REPOSITORY");
+  const runId = ctx.tryGetNonEmpty("GITHUB_RUN_ID");
+
+  if (!repository || !runId) {
+    return undefined;
+  }
+
+  const url = `${serverUrl}/${repository}/actions/runs/${runId}`;
+  return `\n\n---\n*[_View workflow run_](${url})*`;
+}

.github/actions/codex/src/process-label.ts

@@ -0,0 +1,195 @@
+import { fail } from "./fail";
+import { EnvContext } from "./env-context";
+import { renderPromptTemplate } from "./prompt-template";
+
+import { postComment } from "./post-comment";
+import { runCodex } from "./run-codex";
+
+import * as github from "@actions/github";
+import { Config, LabelConfig } from "./config";
+import { maybePublishPRForIssue } from "./git-helpers";
+
+export async function onLabeled(
+  config: Config,
+  ctx: EnvContext,
+): Promise<void> {
+  const GITHUB_EVENT_LABEL_NAME = ctx.get("GITHUB_EVENT_LABEL_NAME");
+  const labelConfig = config.labels[GITHUB_EVENT_LABEL_NAME] as
+    | LabelConfig
+    | undefined;
+  if (!labelConfig) {
+    fail(
+      `Label \`${GITHUB_EVENT_LABEL_NAME}\` not found in config: ${JSON.stringify(config)}`,
+    );
+  }
+
+  await processLabelConfig(ctx, GITHUB_EVENT_LABEL_NAME, labelConfig);
+}
+
+/**
+ * Wrapper that handles `-in-progress` and `-completed` semantics around the core lint/fix/review
+ * processing. It will:
+ *
+ * - Skip execution if the `-in-progress` or `-completed` label is already present.
+ * - Mark the PR/issue as `-in-progress`.
+ * - After successful execution, mark the PR/issue as `-completed`.
+ */
+async function processLabelConfig(
+  ctx: EnvContext,
+  label: string,
+  labelConfig: LabelConfig,
+): Promise<void> {
+  const octokit = ctx.getOctokit();
+  const { owner, repo, issueNumber, labelNames } =
+    await getCurrentLabels(octokit);
+
+  const inProgressLabel = `${label}-in-progress`;
+  const completedLabel = `${label}-completed`;
+  for (const markerLabel of [inProgressLabel, completedLabel]) {
+    if (labelNames.includes(markerLabel)) {
+      console.log(
+        `Label '${markerLabel}' already present on issue/PR #${issueNumber}. Skipping Codex action.`,
+      );
+
+      // Clean up: remove the triggering label to avoid confusion and re-runs.
+      await addAndRemoveLabels(octokit, {
+        owner,
+        repo,
+        issueNumber,
+        remove: markerLabel,
+      });
+
+      return;
+    }
+  }
+
+  // Mark the PR/issue as in progress.
+  await addAndRemoveLabels(octokit, {
+    owner,
+    repo,
+    issueNumber,
+    add: inProgressLabel,
+    remove: label,
+  });
+
+  // Run the core Codex processing.
+  await processLabel(ctx, label, labelConfig);
+
+  // Mark the PR/issue as completed.
+  await addAndRemoveLabels(octokit, {
+    owner,
+    repo,
+    issueNumber,
+    add: completedLabel,
+    remove: inProgressLabel,
+  });
+}
+
+async function processLabel(
+  ctx: EnvContext,
+  label: string,
+  labelConfig: LabelConfig,
+): Promise<void> {
+  const template = labelConfig.getPromptTemplate();
+  const populatedTemplate = await renderPromptTemplate(template, ctx);
+
+  // Always run Codex and post the resulting message as a comment.
+  let commentBody = await runCodex(populatedTemplate, ctx);
+
+  // Current heuristic: only try to create a PR if "attempt" or "fix" is in the
+  // label name. (Yes, we plan to evolve this.)
+  if (label.indexOf("fix") !== -1 || label.indexOf("attempt") !== -1) {
+    console.info(`label ${label} indicates we should attempt to create a PR`);
+    const prUrl = await maybeFixIssue(ctx, commentBody);
+    if (prUrl) {
+      commentBody += `\n\n---\nOpened pull request: ${prUrl}`;
+    }
+  } else {
+    console.info(
+      `label ${label} does not indicate we should attempt to create a PR`,
+    );
+  }
+
+  await postComment(commentBody, ctx);
+}
+
+async function maybeFixIssue(
+  ctx: EnvContext,
+  lastMessage: string,
+): Promise<string | undefined> {
+  // Attempt to create a PR out of any changes Codex produced.
+  const issueNumber = github.context.issue.number!; // exists for issues triggering this path
+  try {
+    return await maybePublishPRForIssue(issueNumber, lastMessage, ctx);
+  } catch (e) {
+    console.warn(`Failed to publish PR: ${e}`);
+  }
+}
+
+async function getCurrentLabels(
+  octokit: ReturnType<typeof github.getOctokit>,
+): Promise<{
+  owner: string;
+  repo: string;
+  issueNumber: number;
+  labelNames: Array<string>;
+}> {
+  const { owner, repo } = github.context.repo;
+  const issueNumber = github.context.issue.number;
+
+  if (!issueNumber) {
+    fail("No issue or pull_request number found in GitHub context.");
+  }
+
+  const { data: issueData } = await octokit.rest.issues.get({
+    owner,
+    repo,
+    issue_number: issueNumber,
+  });
+
+  const labelNames =
+    issueData.labels?.map((label: any) =>
+      typeof label === "string" ? label : label.name,
+    ) ?? [];
+
+  return { owner, repo, issueNumber, labelNames };
+}
+
+async function addAndRemoveLabels(
+  octokit: ReturnType<typeof github.getOctokit>,
+  opts: {
+    owner: string;
+    repo: string;
+    issueNumber: number;
+    add?: string;
+    remove?: string;
+  },
+): Promise<void> {
+  const { owner, repo, issueNumber, add, remove } = opts;
+
+  if (add) {
+    try {
+      await octokit.rest.issues.addLabels({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        labels: [add],
+      });
+    } catch (error) {
+      console.warn(`Failed to add label '${add}': ${error}`);
+    }
+  }
+
+  if (remove) {
+    try {
+      await octokit.rest.issues.removeLabel({
+        owner,
+        repo,
+        issue_number: issueNumber,
+        name: remove,
+      });
+    } catch (error) {
+      console.warn(`Failed to remove label '${remove}': ${error}`);
+    }
+  }
+}

.github/actions/codex/src/prompt-template.ts

@@ -0,0 +1,284 @@
+/*
+ * Utilities to render Codex prompt templates.
+ *
+ * A template is a Markdown (or plain-text) file that may contain one or more
+ * placeholders of the form `{CODEX_ACTION_<NAME>}`. At runtime these
+ * placeholders are substituted with dynamically generated content. Each
+ * placeholder is resolved **exactly once** even if it appears multiple times
+ * in the same template.
+ */
+
+import { readFile } from "fs/promises";
+
+import { EnvContext } from "./env-context";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazily caches parsed `$GITHUB_EVENT_PATH` contents keyed by the file path so
+ * we only hit the filesystem once per unique event payload.
+ */
+const githubEventDataCache: Map<string, Promise<any>> = new Map();
+
+function getGitHubEventData(ctx: EnvContext): Promise<any> {
+  const eventPath = ctx.get("GITHUB_EVENT_PATH");
+  let cached = githubEventDataCache.get(eventPath);
+  if (!cached) {
+    cached = readFile(eventPath, "utf8").then((raw) => JSON.parse(raw));
+    githubEventDataCache.set(eventPath, cached);
+  }
+  return cached;
+}
+
+async function runCommand(args: Array<string>): Promise<string> {
+  const result = Bun.spawnSync(args, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (result.success) {
+    return result.stdout.toString();
+  }
+
+  console.error(`Error running ${JSON.stringify(args)}: ${result.stderr}`);
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+// Regex that captures the variable name without the surrounding { } braces.
+const VAR_REGEX = /\{(CODEX_ACTION_[A-Z0-9_]+)\}/g;
+
+// Cache individual placeholder values so each one is resolved at most once per
+// process even if many templates reference it.
+const placeholderCache: Map<string, Promise<string>> = new Map();
+
+/**
+ * Parse a template string, resolve all placeholders and return the rendered
+ * result.
+ */
+export async function renderPromptTemplate(
+  template: string,
+  ctx: EnvContext,
+): Promise<string> {
+  // ---------------------------------------------------------------------
+  // 1) Gather all *unique* placeholders present in the template.
+  // ---------------------------------------------------------------------
+  const variables = new Set<string>();
+  for (const match of template.matchAll(VAR_REGEX)) {
+    variables.add(match[1]);
+  }
+
+  // ---------------------------------------------------------------------
+  // 2) Kick off (or reuse) async resolution for each variable.
+  // ---------------------------------------------------------------------
+  for (const variable of variables) {
+    if (!placeholderCache.has(variable)) {
+      placeholderCache.set(variable, resolveVariable(variable, ctx));
+    }
+  }
+
+  // ---------------------------------------------------------------------
+  // 3) Await completion so we can perform a simple synchronous replace below.
+  // ---------------------------------------------------------------------
+  const resolvedEntries: [string, string][] = [];
+  for (const [key, promise] of placeholderCache.entries()) {
+    resolvedEntries.push([key, await promise]);
+  }
+  const resolvedMap = new Map<string, string>(resolvedEntries);
+
+  // ---------------------------------------------------------------------
+  // 4) Replace each occurrence.  We use replace with a callback to ensure
+  //    correct substitution even if variable names overlap (they shouldn't,
+  //    but better safe than sorry).
+  // ---------------------------------------------------------------------
+  return template.replace(VAR_REGEX, (_, varName: string) => {
+    return resolvedMap.get(varName) ?? "";
+  });
+}
+
+export async function ensureBaseAndHeadCommitsForPRAreAvailable(
+  ctx: EnvContext,
+): Promise<{ baseSha: string; headSha: string } | null> {
+  const prShas = await getPrShas(ctx);
+  if (prShas == null) {
+    console.warn("Unable to resolve PR branches");
+    return null;
+  }
+
+  const event = await getGitHubEventData(ctx);
+  const pr = event.pull_request;
+  if (!pr) {
+    console.warn("event.pull_request is not defined - unexpected");
+    return null;
+  }
+
+  const workspace = ctx.get("GITHUB_WORKSPACE");
+
+  // Refs (branch names)
+  const baseRef: string | undefined = pr.base?.ref;
+  const headRef: string | undefined = pr.head?.ref;
+
+  // Clone URLs
+  const baseRemoteUrl: string | undefined = pr.base?.repo?.clone_url;
+  const headRemoteUrl: string | undefined = pr.head?.repo?.clone_url;
+
+  if (!baseRef || !headRef || !baseRemoteUrl || !headRemoteUrl) {
+    console.warn(
+      "Missing PR ref or remote URL information - cannot fetch commits",
+    );
+    return null;
+  }
+
+  // Ensure we have the base branch.
+  await runCommand([
+    "git",
+    "-C",
+    workspace,
+    "fetch",
+    "--no-tags",
+    "origin",
+    baseRef,
+  ]);
+
+  // Ensure we have the head branch.
+  if (headRemoteUrl === baseRemoteUrl) {
+    // Same repository – the commit is available from `origin`.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "fetch",
+      "--no-tags",
+      "origin",
+      headRef,
+    ]);
+  } else {
+    // Fork – make sure a `pr` remote exists that points at the fork. Attempting
+    // to add a remote that already exists causes git to error, so we swallow
+    // any non-zero exit codes from that specific command.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "remote",
+      "add",
+      "pr",
+      headRemoteUrl,
+    ]);
+
+    // Whether adding succeeded or the remote already existed, attempt to fetch
+    // the head ref from the `pr` remote.
+    await runCommand([
+      "git",
+      "-C",
+      workspace,
+      "fetch",
+      "--no-tags",
+      "pr",
+      headRef,
+    ]);
+  }
+
+  return prShas;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers – still exported for use by other modules.
+// ---------------------------------------------------------------------------
+
+export async function resolvePrDiff(ctx: EnvContext): Promise<string> {
+  const prShas = await ensureBaseAndHeadCommitsForPRAreAvailable(ctx);
+  if (prShas == null) {
+    console.warn("Unable to resolve PR branches");
+    return "";
+  }
+
+  const workspace = ctx.get("GITHUB_WORKSPACE");
+  const { baseSha, headSha } = prShas;
+  return runCommand([
+    "git",
+    "-C",
+    workspace,
+    "diff",
+    "--color=never",
+    `${baseSha}..${headSha}`,
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Placeholder resolution
+// ---------------------------------------------------------------------------
+
+async function resolveVariable(name: string, ctx: EnvContext): Promise<string> {
+  switch (name) {
+    case "CODEX_ACTION_ISSUE_TITLE": {
+      const event = await getGitHubEventData(ctx);
+      const issue = event.issue ?? event.pull_request;
+      return issue?.title ?? "";
+    }
+
+    case "CODEX_ACTION_ISSUE_BODY": {
+      const event = await getGitHubEventData(ctx);
+      const issue = event.issue ?? event.pull_request;
+      return issue?.body ?? "";
+    }
+
+    case "CODEX_ACTION_GITHUB_EVENT_PATH": {
+      return ctx.get("GITHUB_EVENT_PATH");
+    }
+
+    case "CODEX_ACTION_BASE_REF": {
+      const event = await getGitHubEventData(ctx);
+      return event?.pull_request?.base?.ref ?? "";
+    }
+
+    case "CODEX_ACTION_HEAD_REF": {
+      const event = await getGitHubEventData(ctx);
+      return event?.pull_request?.head?.ref ?? "";
+    }
+
+    case "CODEX_ACTION_PR_DIFF": {
+      return resolvePrDiff(ctx);
+    }
+
+    // -------------------------------------------------------------------
+    // Add new template variables here.
+    // -------------------------------------------------------------------
+
+    default: {
+      // Unknown variable – leave it blank to avoid leaking placeholders to the
+      // final prompt.  The alternative would be to `fail()` here, but silently
+      // ignoring unknown placeholders is more forgiving and better matches the
+      // behaviour of typical template engines.
+      console.warn(`Unknown template variable: ${name}`);
+      return "";
+    }
+  }
+}
+
+async function getPrShas(
+  ctx: EnvContext,
+): Promise<{ baseSha: string; headSha: string } | null> {
+  const event = await getGitHubEventData(ctx);
+  const pr = event.pull_request;
+  if (!pr) {
+    console.warn("event.pull_request is not defined");
+    return null;
+  }
+
+  // Prefer explicit SHAs if available to avoid relying on local branch names.
+  const baseSha: string | undefined = pr.base?.sha;
+  const headSha: string | undefined = pr.head?.sha;
+
+  if (!baseSha || !headSha) {
+    console.warn("one of base or head is not defined on event.pull_request");
+    return null;
+  }
+
+  return { baseSha, headSha };
+}

.github/actions/codex/src/review.ts

@@ -0,0 +1,42 @@
+import type { EnvContext } from "./env-context";
+import { runCodex } from "./run-codex";
+import { postComment } from "./post-comment";
+import { addEyesReaction } from "./add-reaction";
+
+/**
+ * Handle `pull_request_review` events. We treat the review body the same way
+ * as a normal comment.
+ */
+export async function onReview(ctx: EnvContext): Promise<void> {
+  const triggerPhrase = ctx.tryGet("INPUT_TRIGGER_PHRASE");
+  if (!triggerPhrase) {
+    console.warn("Empty trigger phrase: skipping.");
+    return;
+  }
+
+  const reviewBody = ctx.tryGet("GITHUB_EVENT_REVIEW_BODY");
+
+  if (!reviewBody) {
+    console.warn("Review body not found in environment: skipping.");
+    return;
+  }
+
+  if (!reviewBody.includes(triggerPhrase)) {
+    console.log(
+      `Trigger phrase '${triggerPhrase}' not found: nothing to do for this review.`,
+    );
+    return;
+  }
+
+  const prompt = reviewBody.replace(triggerPhrase, "").trim();
+
+  if (prompt.length === 0) {
+    console.warn("Prompt is empty after removing trigger phrase: skipping.");
+    return;
+  }
+
+  await addEyesReaction(ctx);
+
+  const lastMessage = await runCodex(prompt, ctx);
+  await postComment(lastMessage, ctx);
+}

.github/actions/codex/src/run-codex.ts

@@ -0,0 +1,56 @@
+import { fail } from "./fail";
+import { EnvContext } from "./env-context";
+import { tmpdir } from "os";
+import { join } from "node:path";
+import { readFile, mkdtemp } from "fs/promises";
+import { resolveWorkspacePath } from "./github-workspace";
+
+/**
+ * Runs the Codex CLI with the provided prompt and returns the output written
+ * to the "last message" file.
+ */
+export async function runCodex(
+  prompt: string,
+  ctx: EnvContext,
+): Promise<string> {
+  const OPENAI_API_KEY = ctx.get("OPENAI_API_KEY");
+
+  const tempDirPath = await mkdtemp(join(tmpdir(), "codex-"));
+  const lastMessageOutput = join(tempDirPath, "codex-prompt.md");
+
+  const args = ["/usr/local/bin/codex-exec"];
+
+  const inputCodexArgs = ctx.tryGet("INPUT_CODEX_ARGS")?.trim();
+  if (inputCodexArgs) {
+    args.push(...inputCodexArgs.split(/\s+/));
+  }
+
+  args.push("--output-last-message", lastMessageOutput, prompt);
+
+  const env: Record<string, string> = { ...process.env, OPENAI_API_KEY };
+  const INPUT_CODEX_HOME = ctx.tryGet("INPUT_CODEX_HOME");
+  if (INPUT_CODEX_HOME) {
+    env.CODEX_HOME = resolveWorkspacePath(INPUT_CODEX_HOME, ctx);
+  }
+
+  console.log(`Running Codex: ${JSON.stringify(args)}`);
+  const result = Bun.spawnSync(args, {
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  if (!result.success) {
+    fail(`Codex failed: see above for details.`);
+  }
+
+  // Read the output generated by Codex.
+  let lastMessage: string;
+  try {
+    lastMessage = await readFile(lastMessageOutput, "utf8");
+  } catch (err) {
+    fail(`Failed to read Codex output at '${lastMessageOutput}': ${err}`);
+  }
+
+  return lastMessage;
+}

.github/actions/codex/src/verify-inputs.ts

@@ -0,0 +1,33 @@
+// Validate the inputs passed to the composite action.
+// The script currently ensures that the provided configuration file exists and
+// matches the expected schema.
+
+import type { Config } from "./config";
+
+import { existsSync } from "fs";
+import * as path from "path";
+import { fail } from "./fail";
+
+export function performAdditionalValidation(config: Config, workspace: string) {
+  // Additional validation: ensure referenced prompt files exist and are Markdown.
+  for (const [label, details] of Object.entries(config.labels)) {
+    // Determine which prompt key is present (the schema guarantees exactly one).
+    const promptPathStr =
+      (details as any).prompt ?? (details as any).promptPath;
+
+    if (promptPathStr) {
+      const promptPath = path.isAbsolute(promptPathStr)
+        ? promptPathStr
+        : path.join(workspace, promptPathStr);
+
+      if (!existsSync(promptPath)) {
+        fail(`Prompt file for label '${label}' not found: ${promptPath}`);
+      }
+      if (!promptPath.endsWith(".md")) {
+        fail(
+          `Prompt file for label '${label}' must be a .md file (got ${promptPathStr}).`,
+        );
+      }
+    }
+  }
+}