@aspruyt/xfg 2.2.1 → 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");
@@ -299,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})`);
                 }
@@ -341,6 +373,7 @@ export class RepositoryProcessor {
                 retries: this.retries,
                 prTemplate,
                 executor: this.executor,
+                token,
             });
             // Step 10: Handle merge options if configured
             let mergeResult;
@@ -360,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,13 +149,10 @@ export class GraphQLCommitStrategy {
         const hostnameArg = repoInfo.host !== "github.com"
             ? `--hostname ${escapeShellArg(repoInfo.host)}`
             : "";
-        // Use GH_INSTALLATION_TOKEN explicitly for authentication (issue #268)
+        // 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 installationToken = process.env.GH_INSTALLATION_TOKEN;
-        const authArg = installationToken
-            ? `-H "Authorization: token ${installationToken}"`
-            : "";
+        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

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.1",
+  "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",