Enhance deploy output logs for token access (#2862)

Add specific authentication failure messages
Add testcases and update documentation

Author: gerteck

docs/userGuide/deployingTheSite.md

@@ -121,6 +121,33 @@ jobs:
 <box type="info">
 
 The sample `deploy.yml` workflow above uses the [default GitHub Token secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) that is generated automatically for each GitHub Actions workflow. You may also use a [GitHub Personal Access Token](#generating-a-github-personal-access-token) in place of the default GitHub Token.
+
+Note that **Cross-repository deployments require a Personal Access Token (PAT)**, as the built-in `GITHUB_TOKEN` is scoped to the repository that triggered the workflow and **cannot push to a different repository**. If your `site.json` specifies a `deploy.repo` that differs from the repository running the workflow, the deploy will fail with an authentication error.
+
+To deploy to a different repository:
+1. [Generate a PAT](#generating-a-github-personal-access-token) with **Contents: Read and Write** permission
+   (for fine-grained tokens), or **repo** scope (for classic tokens).
+1. Store it as a repository secret (e.g. `PAT_TOKEN`) in the repository running the workflow.
+1. In your workflow file, you can map the secret to an environment variable and provide its name to MarkBind:
+    - **Default Option:** Map the secret to `GITHUB_TOKEN` and use `markbind deploy --ci`.
+      ```yml
+      env:
+        GITHUB_TOKEN: {% raw %}${{ secrets.PAT_TOKEN }}{% endraw %}
+      run: markbind deploy --ci
+      ```
+    - **Custom Option:** Map the secret to an environment variable of your choice (e.g., `MY_TOKEN`) and pass its name to the `--ci` flag.
+      ```yml
+      env:
+        MY_TOKEN: {% raw %}${{ secrets.PAT_TOKEN }}{% endraw %}
+      run: markbind deploy --ci MY_TOKEN
+      ```
+
+<box type="tip">
+
+If you see `markbind deploy` reporting success but your cross-repository site is not updated, check that you are not using the default `GITHUB_TOKEN` for a cross-repository deployment. MarkBind will log a warning if it detects this situation.
+
+</box>
+
 </box>
 
 Once you have created the file, commit and push the file to your repo. 

packages/core/src/Site/SiteDeployManager.ts

@@ -90,8 +90,9 @@ export class SiteDeployManager {
       process.env.CACHE_DIR = cacheDirectory;
     }
 
+    let usingDefaultGithubToken = false;
     if (ciTokenVar) {
-      const ciToken = _.isBoolean(ciTokenVar) ? 'GITHUB_TOKEN' : ciTokenVar;
+      const ciToken = _.isString(ciTokenVar) ? (ciTokenVar as string) : 'GITHUB_TOKEN';
       if (!process.env[ciToken]) {
         throw new Error(`The environment variable ${ciToken} does not exist.`);
       }
@@ -117,6 +118,31 @@ export class SiteDeployManager {
         process.env.CACHE_DIR = path.join(process.env.GITHUB_WORKSPACE || '.cache');
         repoSlug = SiteDeployManager.extractRepoSlug(options.repo, process.env.GITHUB_REPOSITORY);
 
+        // Visit https://docs.github.com/en/authentication/keeping-your-account-and-data-secure
+        //         /about-authentication-to-github#about-authentication-to-github
+        // for more information about the different token formats.
+        const isBuiltInFormat = githubToken.startsWith('ghs_');
+        const isPatFormat = githubToken.startsWith('ghp_') || githubToken.startsWith('github_pat_');
+
+        if (isPatFormat) {
+          usingDefaultGithubToken = false;
+        } else if (isBuiltInFormat) {
+          usingDefaultGithubToken = true;
+        } else {
+          usingDefaultGithubToken = ciToken === 'GITHUB_TOKEN';
+        }
+
+        // Warn early if deploying to a different repo with the default GITHUB_TOKEN,
+        // which is scoped only to the triggering repository.
+        if (
+          usingDefaultGithubToken
+          && repoSlug
+          && process.env.GITHUB_REPOSITORY
+          && repoSlug.toLowerCase() !== process.env.GITHUB_REPOSITORY.toLowerCase()
+        ) {
+          SiteDeployManager.warnCrossRepoToken(repoSlug, process.env.GITHUB_REPOSITORY);
+        }
+
         options.user = {
           name: 'github-actions',
           email: 'github-actions@github.com',
@@ -139,10 +165,52 @@ export class SiteDeployManager {
     }
 
     // Waits for the repo to be updated.
-    await publish(basePath, options);
+    try {
+      await publish(basePath, options);
+    } catch (err) {
+      SiteDeployManager.throwIfAuthError(err, usingDefaultGithubToken);
+      throw err;
+    }
     return options;
   }
 
+  static isAuthError(errMessage: string) {
+    const authErrorPattern = new RegExp(
+      '\\b403\\b|Authentication failed|Permission to'
+      + '|could not read Username|Invalid username',
+      'i',
+    );
+    return authErrorPattern.test(errMessage);
+  }
+
+  static throwIfAuthError(err: unknown, usingDefaultGithubToken: boolean) {
+    // eslint-disable-next-line lodash/prefer-lodash-typecheck
+    const errMessage = (err instanceof Error) ? err.message : String(err);
+    if (!SiteDeployManager.isAuthError(errMessage)) return;
+    const hint = usingDefaultGithubToken
+      ? ('\nThis may be because the built-in GITHUB_TOKEN cannot push to a different repository.\n'
+         + 'Consider using a Personal Access Token (PAT) instead, and ensure it has '
+         + '"repo" scope (classic) or "Contents: Read and Write" (fine-grained) permissions.')
+      : ('\nEnsure your PAT has "repo" scope (classic) or "Contents: Read and Write" (fine-grained) '
+         + 'permissions for the target repository.');
+    const error = new Error(
+      `Deployment failed due to an authentication error: ${errMessage}${hint}`,
+    );
+    (error as any).cause = err;
+    throw error;
+  }
+
+  static warnCrossRepoToken(repoSlug: string | undefined, currentRepo: string | undefined) {
+    logger.warn(
+      'Warning: You are deploying to a repository different from the one running this workflow '
+      + `("${repoSlug}" vs "${currentRepo}").\n`
+      + 'If this is the built-in GITHUB_TOKEN, it is scoped only to the triggering repository and '
+      + 'cannot push to other repositories.\n'
+      + 'If you are using a Personal Access Token (PAT), consider using a custom environment variable '
+      + 'name (e.g. GH_TOKEN) to avoid this warning: markbind deploy --ci GH_TOKEN',
+    );
+  }
+
   /**
    * Extract repo slug from user-specified repo URL so that we can include the access token
    */

packages/core/test/unit/Site/SiteDeployManager.test.ts

@@ -1,4 +1,6 @@
 import fs from 'fs-extra';
+import ghpages from 'gh-pages';
+import * as mockLogger from '../../../src/utils/logger.js';
 import { SiteDeployManager, DeployOptions } from '../../../src/Site/SiteDeployManager.js';
 import { SiteConfig } from '../../../src/Site/SiteConfig.js';
 import { SITE_JSON_DEFAULT } from '../utils/data.js';
@@ -13,6 +15,11 @@ jest.mock('../../../src/utils/git', () => ({
   getRemoteBranchFile: jest.fn(() => Promise.resolve(null)),
   getRemoteUrl: jest.fn(() => Promise.resolve('https://github.com/mock-user/mock-repo.git')),
 }));
+jest.mock('../../../src/utils/logger', () => ({
+  warn: jest.fn(),
+  error: jest.fn(),
+  info: jest.fn(),
+}));
 
 const rootPath = '/tmp/test';
 const outputPath = '/tmp/test/_site';
@@ -26,17 +33,15 @@ const mockGhPages = {
 };
 
 // Mock gh-pages publish
-const ghpages = require('gh-pages');
-
-ghpages.publish = jest.fn((dir: string, options: DeployOptions, callback?: (err?: any) => void) => {
+(ghpages as any).publish = jest.fn((dir: string, options: DeployOptions, callback?: (err?: any) => void) => {
   mockGhPages.dir = dir;
   mockGhPages.options = options;
   if (callback) {
     callback();
   }
   return Promise.resolve();
 });
-ghpages.clean = jest.fn();
+(ghpages as any).clean = jest.fn();
 
 afterEach(() => {
   mockFs.vol.reset();
@@ -105,6 +110,53 @@ test('SiteDeployManager should not deploy without a built site', async () => {
         + 'Please build the site first before deploy.'));
 });
 
+describe('SiteDeployManager.isAuthError', () => {
+  test.each([
+    ['403 error', 'Request failed with status code 403'],
+    ['Authentication failed', 'Authentication failed for repo'],
+    ['Permission to', 'Permission to org/repo denied'],
+    ['could not read Username', 'could not read Username for repo'],
+    ['Invalid username', 'Invalid username or password'],
+  ])('returns true for auth error: %s', (_, message) => {
+    expect(SiteDeployManager.isAuthError(message)).toBe(true);
+  });
+
+  test('returns false for non-auth errors', () => {
+    expect(SiteDeployManager.isAuthError('Network timeout')).toBe(false);
+    expect(SiteDeployManager.isAuthError('branch not found')).toBe(false);
+  });
+});
+
+describe('SiteDeployManager.throwIfAuthError', () => {
+  test('does not throw for non-auth errors', () => {
+    expect(() => SiteDeployManager.throwIfAuthError(new Error('Network timeout'), false)).not.toThrow();
+  });
+
+  test('throws with auth error message (no PAT hint when not using default token)', () => {
+    expect(() => SiteDeployManager.throwIfAuthError(new Error('403 forbidden'), false))
+      .toThrow('Deployment failed due to an authentication error: 403 forbidden');
+  });
+
+  test('throws with PAT hint when using default GITHUB_TOKEN', () => {
+    expect(() => SiteDeployManager.throwIfAuthError(new Error('Authentication failed'), true))
+      .toThrow('GITHUB_TOKEN cannot push to a different repository');
+  });
+
+  test('handles non-Error thrown values', () => {
+    expect(() => SiteDeployManager.throwIfAuthError('403', false))
+      .toThrow('Deployment failed due to an authentication error: 403');
+  });
+});
+
+describe('SiteDeployManager.warnCrossRepoToken', () => {
+  test('logs a warning mentioning both repos', () => {
+    SiteDeployManager.warnCrossRepoToken('other-org/other-repo', 'my-org/my-repo');
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('"other-org/other-repo" vs "my-org/my-repo"'),
+    );
+  });
+});
+
 describe('Site deploy with various CI environments', () => {
   // Keep a copy of the original environment
   const OLD_ENV = { ...process.env };
@@ -287,6 +339,38 @@ describe('Site deploy with various CI environments', () => {
       .toThrow(new Error('-c/--ci expects a GitHub repository.\n'
         + `The specified repository ${invalidRepoConfig.deploy.repo} is not valid.`));
   });
+
+  test('warns when GITHUB_TOKEN is used to deploy to a different repo in GitHub Actions', async () => {
+    process.env.GITHUB_ACTIONS = 'true';
+    process.env.GITHUB_TOKEN = 'githubToken';
+    process.env.GITHUB_REPOSITORY = 'my-org/my-repo';
+
+    const crossRepoConfig = JSON.parse(SITE_JSON_DEFAULT);
+    crossRepoConfig.deploy.repo = 'https://github.com/other-org/other-repo.git';
+    mockFs.vol.fromJSON({ _site: {} }, rootPath);
+
+    const deployManager = new SiteDeployManager(rootPath, outputPath);
+    deployManager.siteConfig = crossRepoConfig as SiteConfig;
+
+    await deployManager.deploy(true);
+    expect(mockLogger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('"other-org/other-repo" vs "my-org/my-repo"'),
+    );
+  });
+
+  test('does not warn when GITHUB_TOKEN deploys to the same repo', async () => {
+    process.env.GITHUB_ACTIONS = 'true';
+    process.env.GITHUB_TOKEN = 'githubToken';
+    process.env.GITHUB_REPOSITORY = 'GENERIC_USER/GENERIC_REPO';
+
+    mockFs.vol.fromJSON({ _site: {} }, rootPath);
+
+    const deployManager = new SiteDeployManager(rootPath, outputPath);
+    deployManager.siteConfig = JSON.parse(SITE_JSON_DEFAULT) as SiteConfig;
+
+    await deployManager.deploy(true);
+    expect(mockLogger.warn).not.toHaveBeenCalled();
+  });
 });
 
 describe('SiteDeployManager URL construction utilities', () => {