@aspruyt/xfg 2.2.0 → 3.0.0

package/dist/github-app-token-manager.d.ts

@@ -0,0 +1,49 @@
+import type { GitHubRepoInfo } from "./repo-detector.js";
+/** Duration to cache tokens (45 minutes in milliseconds) */
+export declare const TOKEN_CACHE_DURATION_MS: number;
+/**
+ * Manages GitHub App authentication tokens for multiple organizations.
+ * Handles JWT generation, installation discovery, and token caching.
+ */
+export declare class GitHubAppTokenManager {
+    private readonly appId;
+    private readonly privateKey;
+    /** Map of "apiHost:owner" -> installation ID */
+    private installations;
+    /** Set of API hosts that have been discovered */
+    private discoveredHosts;
+    /** Map of "apiHost:owner" -> cached token */
+    private tokenCache;
+    constructor(appId: string, privateKey: string);
+    /**
+     * Generates a JWT for GitHub App authentication.
+     * The JWT is signed with RS256 and valid for 10 minutes.
+     */
+    generateJWT(): string;
+    /**
+     * Discovers all installations for this GitHub App on the given API host.
+     * Stores installations in an internal map for later lookup.
+     */
+    discoverInstallations(apiHost: string): Promise<void>;
+    /**
+     * Gets the installation ID for a given owner on the specified API host.
+     * Returns undefined if no installation is found.
+     */
+    getInstallationId(apiHost: string, owner: string): number | undefined;
+    /**
+     * Gets an installation access token for the given owner.
+     * Returns null if no installation is found for the owner.
+     * Tokens are cached for 45 minutes.
+     */
+    getTokenForOwner(apiHost: string, owner: string): Promise<string | null>;
+    /**
+     * Gets an installation access token for a repository.
+     * Automatically discovers installations if not already done for the host.
+     * Derives the API host from the repository host.
+     */
+    getTokenForRepo(repoInfo: GitHubRepoInfo): Promise<string | null>;
+    /**
+     * FOR TESTING ONLY: Manually expire a cached token.
+     */
+    _expireCacheForTesting(apiHost: string, owner: string): void;
+}

package/dist/github-app-token-manager.js

@@ -0,0 +1,173 @@
+import { createSign } from "node:crypto";
+import { withRetry } from "./retry-utils.js";
+/** Duration to cache tokens (45 minutes in milliseconds) */
+export const TOKEN_CACHE_DURATION_MS = 45 * 60 * 1000;
+/**
+ * Manages GitHub App authentication tokens for multiple organizations.
+ * Handles JWT generation, installation discovery, and token caching.
+ */
+export class GitHubAppTokenManager {
+    appId;
+    privateKey;
+    /** Map of "apiHost:owner" -> installation ID */
+    installations = new Map();
+    /** Set of API hosts that have been discovered */
+    discoveredHosts = new Set();
+    /** Map of "apiHost:owner" -> cached token */
+    tokenCache = new Map();
+    constructor(appId, privateKey) {
+        this.appId = appId;
+        this.privateKey = privateKey;
+    }
+    /**
+     * Generates a JWT for GitHub App authentication.
+     * The JWT is signed with RS256 and valid for 10 minutes.
+     */
+    generateJWT() {
+        const now = Math.floor(Date.now() / 1000);
+        const header = {
+            alg: "RS256",
+            typ: "JWT",
+        };
+        const payload = {
+            iat: now - 60, // Issued 60 seconds ago to account for clock drift
+            exp: now + 600, // Expires in 10 minutes
+            iss: this.appId,
+        };
+        const encodedHeader = base64UrlEncode(JSON.stringify(header));
+        const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+        const signatureInput = `${encodedHeader}.${encodedPayload}`;
+        const sign = createSign("RSA-SHA256");
+        sign.update(signatureInput);
+        const signature = sign.sign(this.privateKey);
+        const encodedSignature = base64UrlEncode(signature);
+        return `${encodedHeader}.${encodedPayload}.${encodedSignature}`;
+    }
+    /**
+     * Discovers all installations for this GitHub App on the given API host.
+     * Stores installations in an internal map for later lookup.
+     */
+    async discoverInstallations(apiHost) {
+        const url = `https://${apiHost}/app/installations`;
+        const jwt = this.generateJWT();
+        const response = await withRetry(async () => {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    Accept: "application/vnd.github+json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                },
+            });
+            if (!res.ok) {
+                const status = res.status;
+                // Throw error with status code for retry logic
+                const error = new Error(`GitHub API error: ${status}`);
+                throw error;
+            }
+            return res;
+        });
+        const installations = (await response.json());
+        for (const installation of installations) {
+            const key = `${apiHost}:${installation.account.login}`;
+            this.installations.set(key, installation.id);
+        }
+        this.discoveredHosts.add(apiHost);
+    }
+    /**
+     * Gets the installation ID for a given owner on the specified API host.
+     * Returns undefined if no installation is found.
+     */
+    getInstallationId(apiHost, owner) {
+        const key = `${apiHost}:${owner}`;
+        return this.installations.get(key);
+    }
+    /**
+     * Gets an installation access token for the given owner.
+     * Returns null if no installation is found for the owner.
+     * Tokens are cached for 45 minutes.
+     */
+    async getTokenForOwner(apiHost, owner) {
+        const installationId = this.getInstallationId(apiHost, owner);
+        if (installationId === undefined) {
+            return null;
+        }
+        const cacheKey = `${apiHost}:${owner}`;
+        // Check cache
+        const cached = this.tokenCache.get(cacheKey);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.token;
+        }
+        // Fetch new token
+        const url = `https://${apiHost}/app/installations/${installationId}/access_tokens`;
+        const jwt = this.generateJWT();
+        const response = await withRetry(async () => {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    Accept: "application/vnd.github+json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                },
+            });
+            if (!res.ok) {
+                const status = res.status;
+                const error = new Error(`GitHub API error: ${status}`);
+                throw error;
+            }
+            return res;
+        });
+        const tokenResponse = (await response.json());
+        // Cache the token
+        this.tokenCache.set(cacheKey, {
+            token: tokenResponse.token,
+            expiresAt: Date.now() + TOKEN_CACHE_DURATION_MS,
+        });
+        return tokenResponse.token;
+    }
+    /**
+     * Gets an installation access token for a repository.
+     * Automatically discovers installations if not already done for the host.
+     * Derives the API host from the repository host.
+     */
+    async getTokenForRepo(repoInfo) {
+        const apiHost = deriveApiHost(repoInfo.host);
+        // Auto-discover if needed
+        if (!this.discoveredHosts.has(apiHost)) {
+            await this.discoverInstallations(apiHost);
+        }
+        return this.getTokenForOwner(apiHost, repoInfo.owner);
+    }
+    /**
+     * FOR TESTING ONLY: Manually expire a cached token.
+     */
+    _expireCacheForTesting(apiHost, owner) {
+        const cacheKey = `${apiHost}:${owner}`;
+        const cached = this.tokenCache.get(cacheKey);
+        if (cached) {
+            cached.expiresAt = 0;
+        }
+    }
+}
+/**
+ * Encodes data as base64url (no padding).
+ */
+function base64UrlEncode(data) {
+    const buffer = typeof data === "string" ? Buffer.from(data) : data;
+    return buffer
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/**
+ * Derives the GitHub API host from a repository host.
+ * - github.com -> api.github.com
+ * - ghe.example.com -> ghe.example.com/api/v3
+ */
+function deriveApiHost(host) {
+    if (host === "github.com") {
+        return "api.github.com";
+    }
+    return `${host}/api/v3`;
+}

package/dist/pr-creator.d.ts

@@ -19,6 +19,8 @@ export interface PROptions {
     prTemplate?: string;
     /** Optional command executor for shell commands (for testing) */
     executor?: CommandExecutor;
+    /** GitHub App installation token for authentication */
+    token?: string;
 }
 export interface PRResult {
     url?: string;
@@ -50,5 +52,7 @@ export interface MergePROptions {
     retries?: number;
     /** Optional command executor for shell commands (for testing) */
     executor?: CommandExecutor;
+    /** GitHub App installation token for authentication */
+    token?: string;
 }
 export declare function mergePR(options: MergePROptions): Promise<MergeResult>;

package/dist/pr-creator.js

@@ -97,7 +97,7 @@ export function formatPRTitle(files) {
     return `chore: sync ${changedFiles.length} config files`;
 }
 export async function createPR(options) {
-    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries, prTemplate, executor, } = options;
+    const { repoInfo, branchName, baseBranch, files, workDir, dryRun, retries, prTemplate, executor, token, } = options;
     const title = formatPRTitle(files);
     const body = formatPRBody(files, repoInfo, prTemplate);
     if (dryRun) {
@@ -116,10 +116,11 @@ export async function createPR(options) {
         baseBranch,
         workDir,
         retries,
+        token,
     });
 }
 export async function mergePR(options) {
-    const { repoInfo, prUrl, mergeConfig, workDir, dryRun, retries, executor } = options;
+    const { repoInfo, prUrl, mergeConfig, workDir, dryRun, retries, executor, token, } = options;
     if (dryRun) {
         const modeText = mergeConfig.mode === "force"
             ? "force merge"
@@ -139,5 +140,6 @@ export async function mergePR(options) {
         config: mergeConfig,
         workDir,
         retries,
+        token,
     });
 }

package/dist/repository-processor.d.ts

@@ -43,6 +43,7 @@ export declare class RepositoryProcessor {
     private readonly log;
     private retries;
     private executor;
+    private readonly tokenManager;
     /**
      * Creates a new RepositoryProcessor.
      * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)

package/dist/repository-processor.js

@@ -1,15 +1,16 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { convertContentToString, } from "./config.js";
-import { getRepoDisplayName } from "./repo-detector.js";
+import { getRepoDisplayName, isGitHubRepo, } from "./repo-detector.js";
 import { interpolateXfgContent } from "./xfg-template.js";
 import { GitOps } from "./git-ops.js";
 import { createPR, mergePR } from "./pr-creator.js";
 import { logger } from "./logger.js";
-import { getPRStrategy, getCommitStrategy } from "./strategies/index.js";
+import { getPRStrategy, getCommitStrategy, hasGitHubAppCredentials, } from "./strategies/index.js";
 import { defaultExecutor } from "./command-executor.js";
 import { getFileStatus, generateDiff, createDiffStats, incrementDiffStats, } from "./diff-utils.js";
 import { loadManifest, saveManifest, updateManifest, MANIFEST_FILENAME, } from "./manifest.js";
+import { GitHubAppTokenManager } from "./github-app-token-manager.js";
 /**
  * Determines if a file should be marked as executable.
  * .sh files are auto-executable unless explicit executable: false is set.
@@ -30,6 +31,7 @@ export class RepositoryProcessor {
     log;
     retries = 3;
     executor = defaultExecutor;
+    tokenManager;
     /**
      * Creates a new RepositoryProcessor.
      * @param gitOpsFactory - Optional factory for creating GitOps instances (for testing)
@@ -38,12 +40,40 @@ export class RepositoryProcessor {
     constructor(gitOpsFactory, log) {
         this.gitOpsFactory = gitOpsFactory ?? ((opts) => new GitOps(opts));
         this.log = log ?? logger;
+        // Initialize GitHub App token manager if credentials are configured
+        if (hasGitHubAppCredentials()) {
+            this.tokenManager = new GitHubAppTokenManager(process.env.XFG_GITHUB_APP_ID, process.env.XFG_GITHUB_APP_PRIVATE_KEY);
+        }
+        else {
+            this.tokenManager = null;
+        }
     }
     async process(repoConfig, repoInfo, options) {
         const repoName = getRepoDisplayName(repoInfo);
         const { branchName, workDir, dryRun, prTemplate } = options;
         this.retries = options.retries ?? 3;
         this.executor = options.executor ?? defaultExecutor;
+        // For GitHub repos with token manager, get installation token
+        let token;
+        if (this.tokenManager && isGitHubRepo(repoInfo)) {
+            try {
+                const tokenResult = await this.tokenManager.getTokenForRepo(repoInfo);
+                if (tokenResult === null) {
+                    // No installation found for this owner - skip the repo
+                    return {
+                        success: true,
+                        repoName,
+                        message: `No GitHub App installation found for ${repoInfo.owner}`,
+                        skipped: true,
+                    };
+                }
+                token = tokenResult;
+            }
+            catch (error) {
+                // Token retrieval failed - continue without token and let auth fail naturally
+                this.log.info(`Warning: Failed to get GitHub App token: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         this.gitOps = this.gitOpsFactory({
             workDir,
             dryRun,
@@ -78,6 +108,7 @@ export class RepositoryProcessor {
                     baseBranch,
                     workDir,
                     retries: this.retries,
+                    token,
                 });
                 if (closed) {
                     this.log.info("Closed existing PR and deleted branch for fresh sync");
@@ -101,19 +132,10 @@ export class RepositoryProcessor {
             // - Dry-run: Uses wouldChange() for read-only content comparison (no side effects)
             // - Normal: Uses git status after writing (source of truth for what git will commit)
             //
-            // This is intentional. git status is more accurate because it respects .gitattributes
-            // (line ending normalization, filters) and detects executable bit changes. However,
-            // it requires actually writing files, which defeats dry-run's purpose.
-            //
-            // For config files (JSON/YAML), these approaches produce identical results in practice.
-            // Edge cases (repos with unusual git attributes on config files) are essentially nonexistent.
-            const changedFiles = [];
-            const diffStats = createDiffStats();
-            // Track pre-write actions for non-dry-run mode (issue #252)
-            // We need to know if a file was created vs updated BEFORE writing it
-            const preWriteActions = new Map();
-            // Track file changes for commit strategy (path -> content, null for deletion)
+            // Track all file changes with content and action - single source of truth
+            // Used for both commit message generation and actual commit
             const fileChangesForCommit = new Map();
+            const diffStats = createDiffStats();
             for (const file of repoConfig.files) {
                 const filePath = join(workDir, file.fileName);
                 const fileExistsLocal = existsSync(filePath);
@@ -123,7 +145,10 @@ export class RepositoryProcessor {
                     const existsOnBase = await this.gitOps.fileExistsOnBranch(file.fileName, baseBranch);
                     if (existsOnBase) {
                         this.log.info(`Skipping ${file.fileName} (createOnly: exists on ${baseBranch})`);
-                        changedFiles.push({ fileName: file.fileName, action: "skip" });
+                        fileChangesForCommit.set(file.fileName, {
+                            content: null,
+                            action: "skip",
+                        });
                         continue;
                     }
                 }
@@ -141,37 +166,37 @@ export class RepositoryProcessor {
                     header: file.header,
                     schemaUrl: file.schemaUrl,
                 });
-                // Determine action type (create vs update)
+                // Determine action type (create vs update) BEFORE writing
                 const action = fileExistsLocal
                     ? "update"
                     : "create";
+                // Check if file would change (needed for both modes)
+                const existingContent = this.gitOps.getFileContent(file.fileName);
+                const changed = this.gitOps.wouldChange(file.fileName, fileContent);
+                if (changed) {
+                    // Track in single source of truth
+                    fileChangesForCommit.set(file.fileName, {
+                        content: fileContent,
+                        action,
+                    });
+                }
                 if (dryRun) {
-                    // In dry-run, check if file would change and show diff
-                    const existingContent = this.gitOps.getFileContent(file.fileName);
-                    const changed = this.gitOps.wouldChange(file.fileName, fileContent);
+                    // In dry-run, show diff but don't write
                     const status = getFileStatus(existingContent !== null, changed);
-                    // Track stats
                     incrementDiffStats(diffStats, status);
-                    if (changed) {
-                        changedFiles.push({ fileName: file.fileName, action });
-                    }
-                    // Generate and display diff
                     const diffLines = generateDiff(existingContent, fileContent, file.fileName);
                     this.log.fileDiff(file.fileName, status, diffLines);
                 }
                 else {
-                    // Write the file and store pre-write action for stats calculation
-                    preWriteActions.set(file.fileName, action);
+                    // Write the file
                     this.gitOps.writeFile(file.fileName, fileContent);
-                    // Track content for commit strategy
-                    fileChangesForCommit.set(file.fileName, fileContent);
                 }
             }
             // Step 5b: Set executable permission for files that need it
-            const skippedFileNames = new Set(changedFiles.filter((f) => f.action === "skip").map((f) => f.fileName));
             for (const file of repoConfig.files) {
                 // Skip files that were excluded (createOnly + exists)
-                if (skippedFileNames.has(file.fileName)) {
+                const tracked = fileChangesForCommit.get(file.fileName);
+                if (tracked?.action === "skip") {
                     continue;
                 }
                 if (shouldBeExecutable(file)) {
@@ -195,6 +220,11 @@ export class RepositoryProcessor {
                 for (const fileName of filesToDelete) {
                     // Only delete if file actually exists in the working directory
                     if (this.gitOps.fileExists(fileName)) {
+                        // Track deletion in single source of truth
+                        fileChangesForCommit.set(fileName, {
+                            content: null,
+                            action: "delete",
+                        });
                         if (dryRun) {
                             // In dry-run, show what would be deleted
                             this.log.fileDiff(fileName, "DELETED", []);
@@ -203,10 +233,7 @@ export class RepositoryProcessor {
                         else {
                             this.log.info(`Deleting orphaned file: ${fileName}`);
                             this.gitOps.deleteFile(fileName);
-                            // Track deletion for commit strategy
-                            fileChangesForCommit.set(fileName, null);
                         }
-                        changedFiles.push({ fileName, action: "delete" });
                     }
                 }
             }
@@ -217,85 +244,41 @@ export class RepositoryProcessor {
             // Only save if there are managed files for any config, or if we had a previous manifest
             const hasAnyManagedFiles = Object.keys(newManifest.configs).length > 0;
             if (hasAnyManagedFiles || existingManifest !== null) {
-                if (!dryRun) {
-                    saveManifest(workDir, newManifest);
-                    // Track manifest content for commit strategy
-                    const manifestContent = JSON.stringify(newManifest, null, 2) + "\n";
-                    fileChangesForCommit.set(MANIFEST_FILENAME, manifestContent);
-                }
                 // Track manifest file as changed if it would be different
                 const existingConfigs = existingManifest?.configs ?? {};
                 const manifestChanged = JSON.stringify(existingConfigs) !==
                     JSON.stringify(newManifest.configs);
                 if (manifestChanged) {
                     const manifestExisted = existsSync(join(workDir, MANIFEST_FILENAME));
-                    changedFiles.push({
-                        fileName: MANIFEST_FILENAME,
+                    const manifestContent = JSON.stringify(newManifest, null, 2) + "\n";
+                    fileChangesForCommit.set(MANIFEST_FILENAME, {
+                        content: manifestContent,
                         action: manifestExisted ? "update" : "create",
                     });
                 }
+                if (!dryRun) {
+                    saveManifest(workDir, newManifest);
+                }
             }
             // Show diff summary in dry-run mode
             if (dryRun) {
                 this.log.diffSummary(diffStats.newCount, diffStats.modifiedCount, diffStats.unchangedCount, diffStats.deletedCount);
             }
-            // Step 6: Check for changes (exclude skipped files)
-            let hasChanges;
-            if (dryRun) {
-                hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
-            }
-            else {
-                hasChanges = await this.gitOps.hasChanges();
-                // If there are changes, determine which files changed
-                if (hasChanges) {
-                    // Get the actual list of changed files from git status
-                    const gitChangedFiles = new Set(await this.gitOps.getChangedFiles());
-                    // Build set of files already tracked (skip, delete, manifest updates added earlier)
-                    const alreadyTracked = new Set(changedFiles.map((f) => f.fileName));
-                    // Add config files that actually changed according to git
-                    for (const file of repoConfig.files) {
-                        if (alreadyTracked.has(file.fileName)) {
-                            continue; // Already tracked (skipped, deleted, or manifest)
-                        }
-                        // Only include files that git reports as changed
-                        if (!gitChangedFiles.has(file.fileName)) {
-                            continue; // File didn't actually change
-                        }
-                        // Use pre-write action (issue #252) - we stored whether file existed
-                        // BEFORE writing, which is the correct basis for create vs update
-                        const action = preWriteActions.get(file.fileName) ?? "update";
-                        changedFiles.push({ fileName: file.fileName, action });
-                    }
-                    // Add any other files from git status that aren't already tracked
-                    // This catches files like .xfg.json when manifestChanged was false
-                    // but git still reports a change (e.g., due to formatting differences)
-                    for (const gitFile of gitChangedFiles) {
-                        if (changedFiles.some((f) => f.fileName === gitFile)) {
-                            continue; // Already tracked
-                        }
-                        const filePath = join(workDir, gitFile);
-                        const action = existsSync(filePath)
-                            ? "update"
-                            : "create";
-                        changedFiles.push({ fileName: gitFile, action });
-                    }
-                    // Calculate diff stats from changedFiles (issue #252)
-                    for (const file of changedFiles) {
-                        switch (file.action) {
-                            case "create":
-                                incrementDiffStats(diffStats, "NEW");
-                                break;
-                            case "update":
-                                incrementDiffStats(diffStats, "MODIFIED");
-                                break;
-                            case "delete":
-                                incrementDiffStats(diffStats, "DELETED");
-                                break;
-                            // "skip" files are not counted in stats
-                        }
-                    }
+            // Step 6: Derive changedFiles from single source of truth
+            // This ensures dry-run and non-dry-run modes use identical logic
+            const changedFiles = Array.from(fileChangesForCommit.entries()).map(([fileName, info]) => ({ fileName, action: info.action }));
+            // Calculate diff stats for non-dry-run mode (dry-run already calculated above)
+            if (!dryRun) {
+                for (const [, info] of fileChangesForCommit) {
+                    if (info.action === "create")
+                        incrementDiffStats(diffStats, "NEW");
+                    else if (info.action === "update")
+                        incrementDiffStats(diffStats, "MODIFIED");
+                    else if (info.action === "delete")
+                        incrementDiffStats(diffStats, "DELETED");
                 }
             }
+            const hasChanges = changedFiles.filter((f) => f.action !== "skip").length > 0;
             if (!hasChanges) {
                 return {
                     success: true,
@@ -315,11 +298,10 @@ export class RepositoryProcessor {
                 this.log.info(`Would push to ${pushBranch}...`);
             }
             else {
-                // Build file changes for commit strategy
-                const fileChanges = [];
-                for (const [path, content] of fileChangesForCommit.entries()) {
-                    fileChanges.push({ path, content });
-                }
+                // Build file changes for commit strategy (filter out skipped files)
+                const fileChanges = Array.from(fileChangesForCommit.entries())
+                    .filter(([, info]) => info.action !== "skip")
+                    .map(([path, info]) => ({ path, content: info.content }));
                 // Check if there are actually staged changes (edge case handling)
                 // This handles scenarios where git status shows changes but git add doesn't stage anything
                 // (e.g., due to .gitattributes normalization)
@@ -348,6 +330,7 @@ export class RepositoryProcessor {
                         retries: this.retries,
                         // Use force push (--force-with-lease) for PR branches, not for direct mode
                         force: !isDirectMode,
+                        token,
                     });
                     this.log.info(`Committed: ${commitResult.sha} (verified: ${commitResult.verified})`);
                 }
@@ -390,6 +373,7 @@ export class RepositoryProcessor {
                 retries: this.retries,
                 prTemplate,
                 executor: this.executor,
+                token,
             });
             // Step 10: Handle merge options if configured
             let mergeResult;
@@ -409,6 +393,7 @@ export class RepositoryProcessor {
                     dryRun,
                     retries: this.retries,
                     executor: this.executor,
+                    token,
                 });
                 mergeResult = {
                     merged: result.merged ?? false,

package/dist/strategies/commit-strategy-selector.d.ts

@@ -1,11 +1,17 @@
 import { RepoInfo } from "../repo-detector.js";
 import { CommitStrategy } from "./commit-strategy.js";
 import { CommandExecutor } from "../command-executor.js";
+/**
+ * Checks if GitHub App credentials are configured via environment variables.
+ * Both XFG_GITHUB_APP_ID and XFG_GITHUB_APP_PRIVATE_KEY must be set.
+ */
+export declare function hasGitHubAppCredentials(): boolean;
 /**
  * Factory function to get the appropriate commit strategy for a repository.
  *
- * For GitHub repositories with GH_INSTALLATION_TOKEN set, returns GraphQLCommitStrategy
- * which creates verified commits via the GitHub GraphQL API.
+ * For GitHub repositories with GitHub App credentials (XFG_GITHUB_APP_ID and
+ * XFG_GITHUB_APP_PRIVATE_KEY), returns GraphQLCommitStrategy which creates
+ * verified commits via the GitHub GraphQL API.
  *
  * For all other cases (GitHub with PAT, Azure DevOps, GitLab), returns GitCommitStrategy
  * which uses standard git commands.

package/dist/strategies/commit-strategy-selector.js

@@ -1,11 +1,19 @@
 import { isGitHubRepo } from "../repo-detector.js";
 import { GitCommitStrategy } from "./git-commit-strategy.js";
 import { GraphQLCommitStrategy } from "./graphql-commit-strategy.js";
+/**
+ * Checks if GitHub App credentials are configured via environment variables.
+ * Both XFG_GITHUB_APP_ID and XFG_GITHUB_APP_PRIVATE_KEY must be set.
+ */
+export function hasGitHubAppCredentials() {
+    return !!(process.env.XFG_GITHUB_APP_ID && process.env.XFG_GITHUB_APP_PRIVATE_KEY);
+}
 /**
  * Factory function to get the appropriate commit strategy for a repository.
  *
- * For GitHub repositories with GH_INSTALLATION_TOKEN set, returns GraphQLCommitStrategy
- * which creates verified commits via the GitHub GraphQL API.
+ * For GitHub repositories with GitHub App credentials (XFG_GITHUB_APP_ID and
+ * XFG_GITHUB_APP_PRIVATE_KEY), returns GraphQLCommitStrategy which creates
+ * verified commits via the GitHub GraphQL API.
  *
  * For all other cases (GitHub with PAT, Azure DevOps, GitLab), returns GitCommitStrategy
  * which uses standard git commands.
@@ -14,7 +22,7 @@ import { GraphQLCommitStrategy } from "./graphql-commit-strategy.js";
  * @param executor - Optional command executor for shell commands
  */
 export function getCommitStrategy(repoInfo, executor) {
-    if (isGitHubRepo(repoInfo) && process.env.GH_INSTALLATION_TOKEN) {
+    if (isGitHubRepo(repoInfo) && hasGitHubAppCredentials()) {
         return new GraphQLCommitStrategy(executor);
     }
     return new GitCommitStrategy(executor);

package/dist/strategies/commit-strategy.d.ts

@@ -12,6 +12,8 @@ export interface CommitOptions {
     retries?: number;
     /** Use force push (--force-with-lease). Default: true for PR branches, false for direct push to main. */
     force?: boolean;
+    /** GitHub App installation token for authentication (used by GraphQLCommitStrategy) */
+    token?: string;
 }
 export interface CommitResult {
     sha: string;

package/dist/strategies/github-pr-strategy.d.ts

@@ -8,7 +8,7 @@ export declare class GitHubPRStrategy extends BasePRStrategy {
     /**
      * Check if auto-merge is enabled on the repository.
      */
-    checkAutoMergeEnabled(repoInfo: GitHubRepoInfo, workDir: string, retries?: number): Promise<boolean>;
+    checkAutoMergeEnabled(repoInfo: GitHubRepoInfo, workDir: string, retries?: number, token?: string): Promise<boolean>;
     /**
      * Build merge strategy flag for gh pr merge command.
      */

package/dist/strategies/github-pr-strategy.js

@@ -38,14 +38,21 @@ function buildPRUrlRegex(host) {
     const escapedHost = escapeRegExp(host);
     return new RegExp(`https://${escapedHost}/[\\w-]+/[\\w.-]+/pull/\\d+`);
 }
+/**
+ * Build the GH_TOKEN environment prefix for commands if a token is provided.
+ */
+function buildTokenPrefix(token) {
+    return token ? `GH_TOKEN=${token} ` : "";
+}
 export class GitHubPRStrategy extends BasePRStrategy {
     async checkExistingPR(options) {
-        const { repoInfo, branchName, workDir, retries = 3 } = options;
+        const { repoInfo, branchName, workDir, retries = 3, token } = options;
         if (!isGitHubRepo(repoInfo)) {
             throw new Error("Expected GitHub repository");
         }
         const repoFlag = getRepoFlag(repoInfo);
-        const command = `gh pr list --repo ${escapeShellArg(repoFlag)} --head ${escapeShellArg(branchName)} --json url --jq '.[0].url'`;
+        const tokenPrefix = buildTokenPrefix(token);
+        const command = `${tokenPrefix}gh pr list --repo ${escapeShellArg(repoFlag)} --head ${escapeShellArg(branchName)} --json url --jq '.[0].url'`;
         try {
             const existingPR = await withRetry(() => this.executor.exec(command, workDir), { retries });
             return existingPR || null;
@@ -66,11 +73,11 @@ export class GitHubPRStrategy extends BasePRStrategy {
         }
     }
     async closeExistingPR(options) {
-        const { repoInfo, branchName, baseBranch, workDir, retries = 3 } = options;
+        const { repoInfo, branchName, baseBranch, workDir, retries = 3, token, } = options;
         if (!isGitHubRepo(repoInfo)) {
             throw new Error("Expected GitHub repository");
         }
-        // First check if there's an existing PR
+        // First check if there's an existing PR (pass token through)
         const existingUrl = await this.checkExistingPR({
             repoInfo,
             branchName,
@@ -79,6 +86,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
             retries,
             title: "", // Not used for check
             body: "", // Not used for check
+            token,
         });
         if (!existingUrl) {
             return false;
@@ -89,8 +97,10 @@ export class GitHubPRStrategy extends BasePRStrategy {
             throw new Error(`Could not extract PR number from URL: ${existingUrl}`);
         }
         // Close the PR and delete the branch
+        // Token is passed via GH_TOKEN env prefix for gh CLI authentication
         const repoFlag = getRepoFlag(repoInfo);
-        const command = `gh pr close ${escapeShellArg(prNumber)} --repo ${escapeShellArg(repoFlag)} --delete-branch`;
+        const tokenPrefix = buildTokenPrefix(token);
+        const command = `${tokenPrefix}gh pr close ${escapeShellArg(prNumber)} --repo ${escapeShellArg(repoFlag)} --delete-branch`;
         try {
             await withRetry(() => this.executor.exec(command, workDir), { retries });
             return true;
@@ -102,14 +112,16 @@ export class GitHubPRStrategy extends BasePRStrategy {
         }
     }
     async create(options) {
-        const { repoInfo, title, body, branchName, baseBranch, workDir, retries = 3, } = options;
+        const { repoInfo, title, body, branchName, baseBranch, workDir, retries = 3, token, } = options;
         if (!isGitHubRepo(repoInfo)) {
             throw new Error("Expected GitHub repository");
         }
         // Write body to temp file to avoid shell escaping issues
         const bodyFile = join(workDir, this.bodyFilePath);
         writeFileSync(bodyFile, body, "utf-8");
-        const command = `gh pr create --title ${escapeShellArg(title)} --body-file ${escapeShellArg(bodyFile)} --base ${escapeShellArg(baseBranch)} --head ${escapeShellArg(branchName)}`;
+        // Token is passed via GH_TOKEN env prefix for gh CLI authentication
+        const tokenPrefix = buildTokenPrefix(token);
+        const command = `${tokenPrefix}gh pr create --title ${escapeShellArg(title)} --body-file ${escapeShellArg(bodyFile)} --base ${escapeShellArg(baseBranch)} --head ${escapeShellArg(branchName)}`;
         try {
             const result = await withRetry(() => this.executor.exec(command, workDir), { retries });
             // Extract URL from output - use strict regex for valid PR URLs only
@@ -140,10 +152,12 @@ export class GitHubPRStrategy extends BasePRStrategy {
     /**
      * Check if auto-merge is enabled on the repository.
      */
-    async checkAutoMergeEnabled(repoInfo, workDir, retries = 3) {
+    async checkAutoMergeEnabled(repoInfo, workDir, retries = 3, token) {
         const hostnameFlag = getHostnameFlag(repoInfo);
         const hostnamePart = hostnameFlag ? `${hostnameFlag} ` : "";
-        const command = `gh api ${hostnamePart}repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)} --jq '.allow_auto_merge // false'`;
+        // Token is passed via GH_TOKEN env prefix for gh CLI authentication
+        const tokenPrefix = buildTokenPrefix(token);
+        const command = `${tokenPrefix}gh api ${hostnamePart}repos/${escapeShellArg(repoInfo.owner)}/${escapeShellArg(repoInfo.repo)} --jq '.allow_auto_merge // false'`;
         try {
             const result = await withRetry(() => this.executor.exec(command, workDir), { retries });
             return result.trim() === "true";
@@ -169,7 +183,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
         }
     }
     async merge(options) {
-        const { prUrl, config, workDir, retries = 3 } = options;
+        const { prUrl, config, workDir, retries = 3, token } = options;
         // Manual mode: do nothing
         if (config.mode === "manual") {
             return {
@@ -180,6 +194,8 @@ export class GitHubPRStrategy extends BasePRStrategy {
         }
         const strategyFlag = this.getMergeStrategyFlag(config.strategy);
         const deleteBranchFlag = config.deleteBranch ? "--delete-branch" : "";
+        // Token is passed via GH_TOKEN env prefix for gh CLI authentication
+        const tokenPrefix = buildTokenPrefix(token);
         if (config.mode === "auto") {
             // Check if auto-merge is enabled on the repo
             // Extract host/owner/repo from PR URL (supports both github.com and GHE)
@@ -192,7 +208,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
                     repo: match[3],
                     host: match[1],
                 };
-                const autoMergeEnabled = await this.checkAutoMergeEnabled(repoInfo, workDir, retries);
+                const autoMergeEnabled = await this.checkAutoMergeEnabled(repoInfo, workDir, retries, token);
                 if (!autoMergeEnabled) {
                     logger.info(`Warning: Auto-merge not enabled for '${repoInfo.owner}/${repoInfo.repo}'. PR left open for manual review.`);
                     logger.info(`To enable: gh repo edit ${getRepoFlag(repoInfo)} --enable-auto-merge (requires admin)`);
@@ -205,7 +221,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
                 }
             }
             // Enable auto-merge
-            const command = `gh pr merge ${escapeShellArg(prUrl)} --auto ${strategyFlag} ${deleteBranchFlag}`.trim();
+            const command = `${tokenPrefix}gh pr merge ${escapeShellArg(prUrl)} --auto ${strategyFlag} ${deleteBranchFlag}`.trim();
             try {
                 await withRetry(() => this.executor.exec(command, workDir), {
                     retries,
@@ -228,7 +244,7 @@ export class GitHubPRStrategy extends BasePRStrategy {
         }
         if (config.mode === "force") {
             // Force merge using admin privileges
-            const command = `gh pr merge ${escapeShellArg(prUrl)} --admin ${strategyFlag} ${deleteBranchFlag}`.trim();
+            const command = `${tokenPrefix}gh pr merge ${escapeShellArg(prUrl)} --admin ${strategyFlag} ${deleteBranchFlag}`.trim();
             try {
                 await withRetry(() => this.executor.exec(command, workDir), {
                     retries,

package/dist/strategies/graphql-commit-strategy.js

@@ -49,7 +49,7 @@ export class GraphQLCommitStrategy {
      * @throws Error if repo is not GitHub, payload exceeds 50MB, or API fails
      */
     async commit(options) {
-        const { repoInfo, branchName, message, fileChanges, workDir, retries = 3, } = options;
+        const { repoInfo, branchName, message, fileChanges, workDir, retries = 3, token, } = options;
         // Validate this is a GitHub repo
         if (!isGitHubRepo(repoInfo)) {
             throw new Error(`GraphQL commit strategy requires GitHub repositories. Got: ${repoInfo.type}`);
@@ -83,7 +83,7 @@ export class GraphQLCommitStrategy {
                 // Get the remote HEAD SHA for this branch (not local HEAD)
                 const headSha = await this.executor.exec(`git rev-parse origin/${branchName}`, workDir);
                 // Build and execute the GraphQL mutation
-                const result = await this.executeGraphQLMutation(githubInfo, branchName, message, headSha.trim(), additions, deletions, workDir);
+                const result = await this.executeGraphQLMutation(githubInfo, branchName, message, headSha.trim(), additions, deletions, workDir, token);
                 return result;
             }
             catch (error) {
@@ -103,7 +103,7 @@ export class GraphQLCommitStrategy {
     /**
      * Execute the createCommitOnBranch GraphQL mutation.
      */
-    async executeGraphQLMutation(repoInfo, branchName, message, expectedHeadOid, additions, deletions, workDir) {
+    async executeGraphQLMutation(repoInfo, branchName, message, expectedHeadOid, additions, deletions, workDir, token) {
         const repositoryNameWithOwner = `${repoInfo.owner}/${repoInfo.repo}`;
         // Build file additions with base64 encoding
         const fileAdditions = additions.map((fc) => ({
@@ -149,7 +149,11 @@ export class GraphQLCommitStrategy {
         const hostnameArg = repoInfo.host !== "github.com"
             ? `--hostname ${escapeShellArg(repoInfo.host)}`
             : "";
-        const command = `echo ${escapeShellArg(requestBody)} | gh api graphql ${hostnameArg} --input -`;
+        // Use token parameter for authentication when provided
+        // This ensures the GitHub App is used as the commit author, not github-actions[bot]
+        // The token is passed via Authorization header rather than relying on GH_TOKEN env var
+        const authArg = token ? `-H "Authorization: token ${token}"` : "";
+        const command = `echo ${escapeShellArg(requestBody)} | gh api graphql ${authArg} ${hostnameArg} --input -`;
         const response = await this.executor.exec(command, workDir);
         // Parse the response
         const parsed = JSON.parse(response);

package/dist/strategies/index.d.ts

@@ -9,7 +9,7 @@ export { GitLabPRStrategy } from "./gitlab-pr-strategy.js";
 export type { CommitStrategy, CommitOptions, CommitResult, FileChange, } from "./commit-strategy.js";
 export { GitCommitStrategy } from "./git-commit-strategy.js";
 export { GraphQLCommitStrategy, MAX_PAYLOAD_SIZE, } from "./graphql-commit-strategy.js";
-export { getCommitStrategy } from "./commit-strategy-selector.js";
+export { getCommitStrategy, hasGitHubAppCredentials, } from "./commit-strategy-selector.js";
 /**
  * Factory function to get the appropriate PR strategy for a repository.
  * @param repoInfo - Repository information

package/dist/strategies/index.js

@@ -8,7 +8,7 @@ export { AzurePRStrategy } from "./azure-pr-strategy.js";
 export { GitLabPRStrategy } from "./gitlab-pr-strategy.js";
 export { GitCommitStrategy } from "./git-commit-strategy.js";
 export { GraphQLCommitStrategy, MAX_PAYLOAD_SIZE, } from "./graphql-commit-strategy.js";
-export { getCommitStrategy } from "./commit-strategy-selector.js";
+export { getCommitStrategy, hasGitHubAppCredentials, } from "./commit-strategy-selector.js";
 /**
  * Factory function to get the appropriate PR strategy for a repository.
  * @param repoInfo - Repository information

package/dist/strategies/pr-strategy.d.ts

@@ -23,12 +23,16 @@ export interface PRStrategyOptions {
     workDir: string;
     /** Number of retries for API operations (default: 3) */
     retries?: number;
+    /** GitHub App installation token for authentication */
+    token?: string;
 }
 export interface MergeOptions {
     prUrl: string;
     config: PRMergeConfig;
     workDir: string;
     retries?: number;
+    /** GitHub App installation token for authentication */
+    token?: string;
 }
 /**
  * Options for closing an existing PR.
@@ -39,6 +43,8 @@ export interface CloseExistingPROptions {
     baseBranch: string;
     workDir: string;
     retries?: number;
+    /** GitHub App installation token for authentication */
+    token?: string;
 }
 /**
  * Interface for PR creation strategies (platform-specific implementations).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspruyt/xfg",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "CLI tool to sync JSON, JSON5, YAML, or text configuration files across multiple Git repositories via pull requests or direct push",
   "type": "module",
   "main": "dist/index.js",