patchrelay 0.11.0 → 0.12.1

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.11.0",
-  "commit": "d4b6131b08e4",
-  "builtAt": "2026-03-23T23:29:46.267Z"
+  "version": "0.12.1",
+  "commit": "dfda2eb5c3db",
+  "builtAt": "2026-03-24T13:11:33.565Z"
 }

package/dist/config.js

@@ -3,6 +3,7 @@ import { isIP } from "node:net";
 import path from "node:path";
 import { z } from "zod";
 import { getDefaultConfigPath, getDefaultDatabasePath, getDefaultLogPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getPatchRelayDataDir, } from "./runtime-paths.js";
+import { resolveSecret } from "./resolve-secret.js";
 import { ensureAbsolutePath } from "./utils.js";
 const LINEAR_OAUTH_CALLBACK_PATH = "/oauth/linear/callback";
 const REPO_SETTINGS_DIRNAME = ".patchrelay";
@@ -285,12 +286,12 @@ export function loadConfig(configPath = process.env.PATCHRELAY_CONFIG ?? getDefa
     const parsedFile = parseJsonFile(requestedPath, "config file");
     const parsed = configSchema.parse(withSectionDefaults(expandEnv(parsedFile, env)));
     const requirements = getLoadProfileRequirements(profile);
-    const webhookSecret = env[parsed.linear.webhook_secret_env];
-    const tokenEncryptionKey = env[parsed.linear.token_encryption_key_env];
-    const oauthClientId = env[parsed.linear.oauth.client_id_env];
-    const oauthClientSecret = env[parsed.linear.oauth.client_secret_env];
+    const webhookSecret = resolveSecret("linear-webhook-secret", parsed.linear.webhook_secret_env, env);
+    const tokenEncryptionKey = resolveSecret("token-encryption-key", parsed.linear.token_encryption_key_env, env);
+    const oauthClientId = resolveSecret("linear-oauth-client-id", parsed.linear.oauth.client_id_env, env);
+    const oauthClientSecret = resolveSecret("linear-oauth-client-secret", parsed.linear.oauth.client_secret_env, env);
     const operatorApiToken = parsed.operator_api.bearer_token_env
-        ? env[parsed.operator_api.bearer_token_env]
+        ? resolveSecret("operator-api-token", parsed.operator_api.bearer_token_env, env)
         : undefined;
     if (requirements.requireWebhookSecret && !webhookSecret) {
         throw new Error(`Missing env var ${parsed.linear.webhook_secret_env}`);

package/dist/factory-state.js

@@ -14,11 +14,11 @@ export const ALLOWED_TRANSITIONS = {
     delegated: ["preparing", "failed"],
     preparing: ["implementing", "failed"],
     implementing: ["pr_open", "awaiting_input", "failed", "escalated"],
-    pr_open: ["awaiting_review", "repairing_ci", "failed"],
+    pr_open: ["awaiting_review", "awaiting_queue", "changes_requested", "repairing_ci", "failed"],
     awaiting_review: ["changes_requested", "awaiting_queue", "repairing_ci"],
     changes_requested: ["implementing", "awaiting_input", "escalated"],
     repairing_ci: ["pr_open", "awaiting_review", "escalated", "failed"],
-    awaiting_queue: ["done", "repairing_queue", "repairing_ci"],
+    awaiting_queue: ["done", "repairing_queue", "repairing_ci", "changes_requested"],
     repairing_queue: ["pr_open", "awaiting_review", "awaiting_queue", "escalated", "failed"],
     awaiting_input: ["implementing", "delegated", "escalated"],
     escalated: [],
@@ -34,7 +34,9 @@ export function resolveFactoryStateFromGitHub(triggerEvent, current) {
         case "review_approved":
             return current === "awaiting_review" || current === "pr_open" ? "awaiting_queue" : undefined;
         case "review_changes_requested":
-            return current === "awaiting_review" || current === "pr_open" ? "changes_requested" : undefined;
+            return current === "awaiting_review" || current === "pr_open" || current === "awaiting_queue"
+                ? "changes_requested"
+                : undefined;
         case "review_commented":
             return undefined; // informational only
         case "check_passed":

package/dist/github-app-token.js

@@ -0,0 +1,205 @@
+import { createSign } from "node:crypto";
+import { writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveSecret } from "./resolve-secret.js";
+import { getPatchRelayDataDir } from "./runtime-paths.js";
+const TOKEN_REFRESH_MS = 30 * 60_000; // 30 minutes (tokens last 1 hour)
+/**
+ * Resolve credentials from environment. Returns undefined if not configured.
+ *
+ * The private key is resolved via the provider-agnostic `resolveSecret`:
+ *   1. `$CREDENTIALS_DIRECTORY/github-app-pem`  (systemd-creds)
+ *   2. `$PATCHRELAY_GITHUB_APP_PRIVATE_KEY_FILE` (explicit file path)
+ *   3. `$PATCHRELAY_GITHUB_APP_PRIVATE_KEY`      (direct env var)
+ */
+export function resolveGitHubAppCredentials() {
+    const appId = process.env.PATCHRELAY_GITHUB_APP_ID;
+    const privateKey = resolveSecret("github-app-pem", "PATCHRELAY_GITHUB_APP_PRIVATE_KEY");
+    if (!appId || !privateKey)
+        return undefined;
+    const installationId = process.env.PATCHRELAY_GITHUB_APP_INSTALLATION_ID;
+    return {
+        appId,
+        privateKey,
+        ...(installationId ? { installationId } : {}),
+    };
+}
+/**
+ * Well-known paths for the token file and the gh wrapper.
+ */
+export function getGitHubAppPaths() {
+    const shareDir = getPatchRelayDataDir();
+    return {
+        tokenFile: path.join(shareDir, "gh-token"),
+        binDir: path.join(shareDir, "bin"),
+        ghWrapper: path.join(shareDir, "bin", "gh"),
+    };
+}
+/**
+ * Create the gh wrapper script that reads the token file.
+ * Idempotent — safe to call on every startup.
+ */
+export async function ensureGhWrapper(logger) {
+    const { binDir, ghWrapper, tokenFile } = getGitHubAppPaths();
+    await mkdir(binDir, { recursive: true });
+    const script = `#!/bin/bash
+# PatchRelay gh wrapper — uses GitHub App token when available.
+# Falls through to the user's own gh auth if the token file is missing.
+TOKEN_FILE="${tokenFile}"
+if [ -f "$TOKEN_FILE" ]; then
+  export GH_TOKEN=$(cat "$TOKEN_FILE")
+fi
+exec /usr/bin/gh "$@"
+`;
+    await writeFile(ghWrapper, script, { mode: 0o755 });
+    logger.debug({ path: ghWrapper }, "Wrote gh wrapper script");
+}
+/**
+ * Generate a GitHub App JWT (RS256, 10-minute lifetime).
+ */
+function generateJwt(appId, privateKey) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
+    const payload = Buffer.from(JSON.stringify({
+        iat: now - 60, // 60s clock drift allowance
+        exp: now + 600, // 10 minutes
+        iss: appId,
+    })).toString("base64url");
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${payload}`);
+    const signature = signer.sign(privateKey, "base64url");
+    return `${header}.${payload}.${signature}`;
+}
+/**
+ * Exchange a JWT for an installation access token (1-hour lifetime).
+ */
+async function fetchInstallationToken(jwt, installationId) {
+    const response = await fetch(`https://api.github.com/app/installations/${installationId}/access_tokens`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to fetch installation token (${response.status}): ${body}`);
+    }
+    const data = await response.json();
+    return data.token;
+}
+/**
+ * Find the first installation ID for this app. Called once if installationId
+ * is not pre-configured.
+ */
+async function resolveInstallationId(jwt) {
+    const response = await fetch("https://api.github.com/app/installations", {
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to list installations (${response.status}): ${body}`);
+    }
+    const installations = await response.json();
+    const first = installations[0];
+    if (!first) {
+        throw new Error("GitHub App has no installations. Install it on a repository first.");
+    }
+    return String(first.id);
+}
+/**
+ * Creates a token manager that writes a fresh GitHub App installation token
+ * to a well-known file every 30 minutes. The gh wrapper script reads this file.
+ *
+ * Returns undefined if credentials are not configured (optional feature).
+ */
+export function createGitHubAppTokenManager(credentials, logger) {
+    const { tokenFile } = getGitHubAppPaths();
+    let timer;
+    let resolvedInstallationId = credentials.installationId;
+    let cachedToken;
+    let resolvedBotIdentity;
+    async function refresh() {
+        try {
+            const jwt = generateJwt(credentials.appId, credentials.privateKey);
+            if (!resolvedInstallationId) {
+                resolvedInstallationId = await resolveInstallationId(jwt);
+                logger.info({ installationId: resolvedInstallationId }, "Resolved GitHub App installation ID");
+            }
+            if (!resolvedBotIdentity) {
+                resolvedBotIdentity = await resolveBotIdentity(jwt);
+                logger.info({ botName: resolvedBotIdentity.name, botEmail: resolvedBotIdentity.email }, "Resolved GitHub App bot identity");
+            }
+            const token = await fetchInstallationToken(jwt, resolvedInstallationId);
+            await mkdir(path.dirname(tokenFile), { recursive: true });
+            await writeFile(tokenFile, token, { mode: 0o600 });
+            cachedToken = token;
+            logger.debug("Refreshed GitHub App installation token");
+        }
+        catch (error) {
+            logger.warn({ error: error instanceof Error ? error.message : String(error) }, "Failed to refresh GitHub App token (will retry in 30 minutes)");
+        }
+    }
+    function schedule() {
+        timer = setTimeout(() => {
+            void refresh().finally(schedule);
+        }, TOKEN_REFRESH_MS);
+        timer.unref?.();
+    }
+    return {
+        async start() {
+            await refresh();
+            schedule();
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        currentToken() {
+            return cachedToken;
+        },
+        botIdentity() {
+            return resolvedBotIdentity;
+        },
+    };
+}
+/**
+ * Resolve the bot user identity (name + noreply email) from the GitHub API.
+ * The bot user ID (not the App ID) is required for the noreply email —
+ * using the App ID causes the [bot] badge to not render on commits.
+ */
+async function resolveBotIdentity(jwt) {
+    const response = await fetch("https://api.github.com/app", {
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to fetch app info (${response.status}): ${body}`);
+    }
+    const app = await response.json();
+    const botLogin = `${app.slug}[bot]`;
+    // Fetch the bot user to get the user ID (different from App ID)
+    const userResponse = await fetch(`https://api.github.com/users/${encodeURIComponent(botLogin)}`, {
+        headers: { Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+    });
+    if (!userResponse.ok) {
+        const body = await userResponse.text();
+        throw new Error(`Failed to fetch bot user ${botLogin} (${userResponse.status}): ${body}`);
+    }
+    const user = await userResponse.json();
+    return {
+        name: user.login,
+        email: `${user.id}+${user.login}@users.noreply.github.com`,
+    };
+}

package/dist/github-webhook-handler.js

@@ -1,5 +1,6 @@
 import { resolveFactoryStateFromGitHub } from "./factory-state.js";
 import { normalizeGitHubWebhook, verifyGitHubWebhookSignature } from "./github-webhooks.js";
+import { resolveSecret } from "./resolve-secret.js";
 import { safeJsonParse } from "./utils.js";
 /**
  * GitHub sends both check_run and check_suite completion events.
@@ -73,7 +74,7 @@ export class GitHubWebhookHandler {
             ? this.config.projects.find((p) => p.github?.repoFullName === repoName)
             : undefined;
         // Verify signature using global GitHub App webhook secret
-        const webhookSecret = process.env.GITHUB_APP_WEBHOOK_SECRET;
+        const webhookSecret = resolveSecret("github-app-webhook-secret", "GITHUB_APP_WEBHOOK_SECRET");
         if (webhookSecret) {
             if (!verifyGitHubWebhookSignature(params.rawBody, webhookSecret, params.signature)) {
                 return { status: 401, body: { ok: false, reason: "invalid_signature" } };

package/dist/merge-queue.js

@@ -97,7 +97,7 @@ export class MergeQueue {
                     projectId: issue.projectId,
                     stage: "awaiting_queue",
                     status: "blocked",
-                    summary: "Branch up to date but auto-merge not enabled — set GITHUB_TOKEN to unblock",
+                    summary: "Branch up to date but auto-merge not enabled — check gh auth and repo settings",
                 });
             }
             return;
@@ -123,9 +123,19 @@ export class MergeQueue {
             summary: `Branch updated to latest ${baseBranch} — CI will run`,
         });
     }
+    /**
+     * Seed the merge queue on startup: for each project, ensure the front-of-queue
+     * issue has pendingMergePrep set. Catches issues that entered awaiting_queue
+     * but whose merge prep was never triggered or was lost to a crash/restart.
+     */
+    seedOnStartup() {
+        for (const project of this.config.projects) {
+            this.advanceQueue(project.id);
+        }
+    }
     /**
      * Advance the queue: find the next awaiting_queue issue and prepare it.
-     * Called when a PR merges (pr_merged event).
+     * Called when a PR merges (pr_merged event) and on startup.
      */
     advanceQueue(projectId) {
         const queue = this.db.listIssuesByState(projectId, "awaiting_queue");
@@ -138,14 +148,9 @@ export class MergeQueue {
     }
     /** Returns true if auto-merge was successfully enabled (or already enabled). */
     async enableAutoMerge(issue, repoFullName) {
-        const token = process.env.GITHUB_TOKEN;
-        if (!token) {
-            this.logger.warn({ issueKey: issue.issueKey }, "Merge prep: GITHUB_TOKEN not set — auto-merge cannot be enabled");
-            return false;
-        }
+        // Uses the host's existing gh auth — same credentials Codex uses to create PRs.
         const result = await execCommand("gh", ["pr", "merge", String(issue.prNumber), "--repo", repoFullName, "--auto", "--squash"], {
             timeoutMs: 30_000,
-            env: { ...process.env, GH_TOKEN: token },
         });
         if (result.exitCode !== 0) {
             this.logger.warn({ issueKey: issue.issueKey, stderr: result.stderr?.slice(0, 200) }, "Merge prep: auto-merge enablement failed");

package/dist/resolve-secret.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve a secret value using a three-level fallback:
+ *
+ * 1. `$CREDENTIALS_DIRECTORY/<credentialName>` — systemd-creds, Docker secrets,
+ *    or any provider that mounts secrets as files in a private directory.
+ * 2. `${envKey}_FILE` — reads the secret from an arbitrary file path.
+ *    Works with any file-based provider (age, sops, mounted volumes).
+ * 3. `$envKey` — direct environment variable (dev, `op run`, `sops exec-env`,
+ *    or the legacy `service.env` EnvironmentFile).
+ *
+ * Returns `undefined` when the secret is not found at any level.
+ */
+export function resolveSecret(credentialName, envKey, env = process.env) {
+    // 1. systemd credentials directory (private mount, highest trust)
+    const credDir = process.env.CREDENTIALS_DIRECTORY;
+    if (credDir) {
+        try {
+            return readFileSync(path.join(credDir, credentialName), "utf8").trim();
+        }
+        catch {
+            // credential not in this directory — fall through
+        }
+    }
+    // 2. _FILE convention (works with any file-based provider)
+    const filePath = env[`${envKey}_FILE`];
+    if (filePath) {
+        try {
+            return readFileSync(filePath, "utf8").trim();
+        }
+        catch {
+            // file not readable — fall through
+        }
+    }
+    // 3. Direct env var
+    return env[envKey] || undefined;
+}

package/dist/run-orchestrator.js

@@ -5,6 +5,7 @@ import { buildRunningSessionPlan, buildCompletedSessionPlan, buildFailedSessionP
 import { buildStageReport, countEventMethods, extractTurnId, resolveRunCompletionStatus, summarizeCurrentThread, } from "./run-reporting.js";
 import { WorktreeManager } from "./worktree-manager.js";
 import { resolveAuthoritativeLinearStopState } from "./linear-workflow.js";
+import { execCommand } from "./utils.js";
 const DEFAULT_CI_REPAIR_BUDGET = 2;
 const DEFAULT_QUEUE_REPAIR_BUDGET = 2;
 function slugify(value) {
@@ -66,6 +67,7 @@ export class RunOrchestrator {
     logger;
     feed;
     worktreeManager;
+    botIdentity;
     constructor(config, db, codex, linearProvider, enqueueIssue, logger, feed) {
         this.config = config;
         this.db = db;
@@ -155,6 +157,12 @@ export class RunOrchestrator {
         try {
             // Ensure worktree
             await this.worktreeManager.ensureIssueWorktree(project.repoPath, project.worktreeRoot, worktreePath, branchName, { allowExistingOutsideRoot: issue.branchName !== undefined });
+            // Set bot git identity when GitHub App is configured
+            if (this.botIdentity) {
+                const gitBin = this.config.runner.gitBin;
+                await execCommand(gitBin, ["-C", worktreePath, "config", "user.name", this.botIdentity.name], { timeoutMs: 5_000 });
+                await execCommand(gitBin, ["-C", worktreePath, "config", "user.email", this.botIdentity.email], { timeoutMs: 5_000 });
+            }
             // Run prepare-worktree hook
             const hookEnv = buildHookEnv(issue.issueKey ?? issue.linearIssueId, branchName, runType, worktreePath);
             const prepareResult = await runProjectHook(project.repoPath, "prepare-worktree", { cwd: worktreePath, env: hookEnv });
@@ -163,8 +171,18 @@ export class RunOrchestrator {
             }
             // Reuse the existing thread only for review_fix (reviewer context matters).
             // Implementation, ci_repair, and queue_repair get fresh threads.
+            // Fall back to a fresh thread if the stored one is stale (e.g. after app-server restart).
             if (issue.threadId && runType === "review_fix") {
-                threadId = issue.threadId;
+                try {
+                    await this.codex.readThread(issue.threadId, false);
+                    threadId = issue.threadId;
+                }
+                catch {
+                    this.logger.info({ issueKey: issue.issueKey, staleThreadId: issue.threadId }, "Stored thread is stale, starting fresh for review_fix");
+                    const thread = await this.codex.startThread({ cwd: worktreePath });
+                    threadId = thread.id;
+                    this.db.upsertIssue({ projectId: item.projectId, linearIssueId: item.issueId, threadId });
+                }
             }
             else {
                 const thread = await this.codex.startThread({ cwd: worktreePath });

package/dist/service.js

@@ -1,3 +1,4 @@
+import { resolveGitHubAppCredentials, createGitHubAppTokenManager, ensureGhWrapper, } from "./github-app-token.js";
 import { GitHubWebhookHandler } from "./github-webhook-handler.js";
 import { IssueQueryService } from "./issue-query-service.js";
 import { LinearOAuthService } from "./linear-oauth-service.js";
@@ -16,6 +17,7 @@ export class PatchRelayService {
     linearProvider;
     orchestrator;
     mergeQueue;
+    githubAppTokenManager;
     webhookHandler;
     githubWebhookHandler;
     oauthService;
@@ -64,14 +66,29 @@ export class PatchRelayService {
         this.oauthService = new LinearOAuthService(config, { linearInstallations: db.linearInstallations }, logger);
         this.queryService = new IssueQueryService(db, codex, this.orchestrator);
         this.runtime = runtime;
+        // Optional GitHub App token management for bot identity
+        const ghAppCredentials = resolveGitHubAppCredentials();
+        if (ghAppCredentials) {
+            this.githubAppTokenManager = createGitHubAppTokenManager(ghAppCredentials, logger);
+        }
         this.codex.on("notification", (notification) => {
             void this.orchestrator.handleCodexNotification(notification);
         });
     }
     async start() {
+        if (this.githubAppTokenManager) {
+            await ensureGhWrapper(this.logger);
+            await this.githubAppTokenManager.start();
+            const identity = this.githubAppTokenManager.botIdentity();
+            if (identity) {
+                this.orchestrator.botIdentity = identity;
+            }
+        }
         await this.runtime.start();
+        this.mergeQueue.seedOnStartup();
     }
     stop() {
+        this.githubAppTokenManager?.stop();
         this.runtime.stop();
     }
     async createLinearOAuthStart(params) {

package/infra/patchrelay.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=PatchRelay (systemd user service)
+Description=PatchRelay
 After=network-online.target
 Wants=network-online.target
 StartLimitIntervalSec=60
@@ -7,24 +7,47 @@ StartLimitBurst=8
 
 [Service]
 Type=simple
+User=your-user
+Group=your-user
 WorkingDirectory=/home/your-user
+
+# Non-secret config: runtime overrides (paths, log level) and
+# service-only identifiers (GitHub App IDs, etc.)
 EnvironmentFile=-/home/your-user/.config/patchrelay/runtime.env
-EnvironmentFile=/home/your-user/.config/patchrelay/service.env
+EnvironmentFile=-/home/your-user/.config/patchrelay/service.env
 Environment=NODE_ENV=production
 Environment=PATCHRELAY_CONFIG=/home/your-user/.config/patchrelay/patchrelay.json
-Environment=PATH=/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=/home/your-user/.local/share/patchrelay/bin:/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin
+
+# Secrets — encrypted at rest via systemd-creds, decrypted into a private
+# ramfs at $CREDENTIALS_DIRECTORY visible only to this service.
+# See docs/secrets.md for setup instructions.
+#
+# When credstore is not configured, PatchRelay falls back to reading secrets
+# from env vars (EnvironmentFile, op run, etc.) via the resolve-secret module.
+LoadCredentialEncrypted=linear-webhook-secret
+LoadCredentialEncrypted=token-encryption-key
+LoadCredentialEncrypted=linear-oauth-client-id
+LoadCredentialEncrypted=linear-oauth-client-secret
+# Uncomment when GitHub App integration is configured:
+# LoadCredentialEncrypted=github-app-pem
+# LoadCredentialEncrypted=github-app-webhook-secret
+
 ExecStart=/usr/bin/env patchrelay serve
 Restart=on-failure
 RestartSec=5
+
+# Hardening
 NoNewPrivileges=true
 PrivateTmp=true
-ProtectSystem=full
+PrivateMounts=true
+ProtectSystem=strict
 ProtectHome=false
 ReadWritePaths=/home/your-user/.config/patchrelay /home/your-user/.local/state/patchrelay /home/your-user/.local/share/patchrelay
 
-# PatchRelay is intended to run as your real user so Codex inherits your
-# existing git, SSH, and local tool permissions.
-# Add your managed repository roots to ReadWritePaths if you keep hardening enabled.
+# PatchRelay runs as your real user so Codex inherits your existing git,
+# SSH, and local tool permissions.
+# Add your managed repository roots to ReadWritePaths.
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "license": "MIT",
   "type": "module",
   "repository": {

package/service.env.example

@@ -1,7 +1,25 @@
-# PatchRelay service secrets.
-# Keep these values at the machine level for this PatchRelay instance.
+# PatchRelay service-only configuration.
+#
+# Secrets in this file are generated by `patchrelay init` for initial setup.
+# For production, encrypt them with systemd-creds and remove the plaintext
+# values below.  See docs/secrets.md.
+#
+# Non-secret service identifiers (GitHub App IDs) stay here permanently.
 
 LINEAR_WEBHOOK_SECRET=replace-with-linear-webhook-secret
 PATCHRELAY_TOKEN_ENCRYPTION_KEY=replace-with-long-random-secret
 LINEAR_OAUTH_CLIENT_ID=replace-with-linear-oauth-client-id
 LINEAR_OAUTH_CLIENT_SECRET=replace-with-linear-oauth-client-secret
+
+# Optional: GitHub App for bot identity.
+# When configured, PatchRelay generates short-lived installation tokens
+# and writes a gh wrapper so Codex operates as app-name[bot].
+# Create a GitHub App at Settings > Developer settings > GitHub Apps.
+#
+# The private key resolves through the provider-agnostic fallback:
+#   1. $CREDENTIALS_DIRECTORY/github-app-pem      (systemd-creds)
+#   2. PATCHRELAY_GITHUB_APP_PRIVATE_KEY_FILE      (path to PEM file)
+#   3. PATCHRELAY_GITHUB_APP_PRIVATE_KEY           (inline PEM string)
+#
+# PATCHRELAY_GITHUB_APP_ID=123456
+# PATCHRELAY_GITHUB_APP_INSTALLATION_ID=optional-skip-auto-discovery