Actionable guidance when a commit email is not linked to GitHub

When a commit author's email does not map to any GitHub user, the
action can't tell whether that contributor has signed the CLA. Before:
the PR comment buried this as a one-line aside ('Alice seems not to
be a GitHub user. You need a GitHub account...'), which leaves the
contributor unsure what to actually do.

Now: the PR comment includes a dedicated '> [!WARNING]' block that
spells out the exact email address(es) that failed to match, and
gives two concrete remediation paths:

  1. Link the email at github.com/settings/emails. (One-click fix if
     the contributor already has a GitHub account.)
  2. Rewrite the commits using an address that is already linked,
     with the exact git rebase command included.

Implementation:
- graphql.ts now preserves the commit author's email when the commit
  is not linked to a GitHub user, by extending Committer with an
  optional 'email' field. Deduplication now keys on (id, email, name)
  so two different unlinked addresses produce two entries but two
  commits from the same unlinked address collapse.
- pullRequestCommentContent.ts extracts renderUnlinkedCommitBlock(),
  which renders the new warning block. The existing 'not a GitHub
  user' aside is removed.

Tests:
- commentContent unit: one unlinked / multiple unlinked / missing
  email fallback.
- scenarios integration: PR with a commit by 'typo@example.com' (no
  login) produces a bot comment containing the warning block, the
  email, and both remediation options.

Author: iainmcgin

CHANGELOG.md

@@ -9,6 +9,19 @@ the logical unit of work. Each entry links to the commit that introduced it.
 
 ## Unreleased
 
+### Added
+- **Dedicated "unlinked email" guidance on unknown committers.** When a commit
+  author's email is not linked to any GitHub user, the bot now posts a
+  prominent `> [!WARNING]` block that lists each unlinked email and gives the
+  contributor two concrete remediation paths (link the email at
+  `github.com/settings/emails`, or rewrite the commits with a known email
+  using the exact git commands). Previously this case rendered as a terse
+  aside on the main pending-signatures comment with generic "not a GitHub
+  user" copy. The commit author's email is now carried through the GraphQL
+  committers query and attached to `Committer.email` so the comment can
+  surface the specific address that failed to match.
+
+
 ### Code-review pass (April 2026)
 
 Driven by `PLAN.md` following a deep review. Seven phases:

__tests__/integration/scenarios.test.ts

@@ -285,4 +285,49 @@ describe('CLA action end-to-end scenarios', () => {
     ).toEqual([])
     watch.restore()
   })
+
+  it('PR with a commit authored by an email not linked to any GitHub user: posts the unlinked-email warning', async () => {
+    const watch = watchCore()
+    fake.repo('acme', 'widgets').addPullRequest({
+      number: 12,
+      head: { sha: 'headsha', ref: 'feature/email' },
+      // No `login` / `id` — this maps to an unknown committer in the action.
+      commits: [
+        { author: { name: 'Mystery Contributor', email: 'typo@example.com' } }
+      ]
+    })
+    fake
+      .repo('acme', 'widgets')
+      .setFile('signatures/cla.json', { signedContributors: [] })
+
+    setContext({
+      owner: 'acme',
+      repo: 'widgets',
+      issueNumber: 12,
+      actor: 'mystery',
+      eventName: 'pull_request_target',
+      payload: {
+        pull_request: { number: 12, state: 'open' },
+        repository: { id: fake.repo('acme', 'widgets').state.id },
+        action: 'opened'
+      }
+    })
+
+    await runAction()
+
+    const comments = fake.repo('acme', 'widgets').listComments(12)
+    expect(comments).toHaveLength(1)
+    const body = comments[0]!.body
+    // The warning block, the email, and both remediation paths.
+    expect(body).toContain('[!WARNING]')
+    expect(body).toContain('typo@example.com')
+    expect(body).toContain('github.com/settings/emails')
+    expect(body).toContain('Rewrite the commits')
+    // Still marked failed — the action cannot tell whether this committer
+    // has signed.
+    expect(watch.failures.join('\n')).toMatch(
+      /Committers of Pull Request number 12/
+    )
+    watch.restore()
+  })
 })

__tests__/unit/commentContent.test.ts

@@ -61,15 +61,61 @@ describe('commentContent (CLA mode)', () => {
     expect(body).toContain('ask that you all sign')
   })
 
-  it('mentions unknown (non-GitHub-user) committers separately', () => {
-    const body = commentContent(
-      false,
-      committerMap({
-        unknown: [{ name: 'typo@example.com', id: 0, pullRequestNo: 7 }]
-      })
-    )
-    expect(body).toContain('typo@example.com')
-    expect(body).toContain('seems not to be a GitHub user')
+  describe('unlinked-email block', () => {
+    it('surfaces a warning with the email and both fix options when exactly one commit has an unlinked author', () => {
+      const body = commentContent(
+        false,
+        committerMap({
+          unknown: [
+            {
+              name: 'Alice',
+              id: 0,
+              pullRequestNo: 7,
+              email: 'alice@example.com'
+            }
+          ]
+        })
+      )
+      expect(body).toContain('[!WARNING]')
+      expect(body).toContain('1 commit in this PR was authored')
+      expect(body).toContain('alice@example.com')
+      // Both fix options must be present.
+      expect(body).toContain('github.com/settings/emails')
+      expect(body).toContain('Rewrite the commits')
+      expect(body).toContain('git rebase -i --root')
+    })
+
+    it('uses plural phrasing for multiple unlinked authors and includes every email', () => {
+      const body = commentContent(
+        false,
+        committerMap({
+          unknown: [
+            {
+              name: 'Alice',
+              id: 0,
+              pullRequestNo: 7,
+              email: 'alice@example.com'
+            },
+            { name: 'Bob', id: 0, pullRequestNo: 7, email: 'bob@example.com' }
+          ]
+        })
+      )
+      expect(body).toContain('2 commits in this PR were authored')
+      expect(body).toContain('alice@example.com')
+      expect(body).toContain('bob@example.com')
+    })
+
+    it('falls back to the committer name when the email is missing', () => {
+      const body = commentContent(
+        false,
+        committerMap({
+          unknown: [{ name: 'typo-name', id: 0, pullRequestNo: 7 }]
+        })
+      )
+      expect(body).toContain('typo-name')
+      // No email markdown / no backticks around missing email.
+      expect(body).not.toMatch(/`<\s*>`/)
+    })
   })
 
   it('adds the "recheck" hint when suggest-recheck is true', () => {

dist/index.js

@@ -30281,8 +30281,9 @@ query($owner:String! $name:String! $number:Int! $cursor:String){
 }`;
 function getCommitters() {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
         try {
-            const seenNames = new Set();
+            const seenKeys = new Set();
             const committers = [];
             let cursor = null;
             let hasNextPage = true;
@@ -30295,14 +30296,18 @@ function getCommitters() {
                 }));
                 const page = response.repository.pullRequest.commits;
                 for (const edge of page.edges) {
-                    const actor = extractUserFromCommit(edge.node.commit);
-                    const user = {
-                        name: actor.login || actor.name || '',
-                        id: actor.databaseId || 0,
-                        pullRequestNo: github_1.context.issue.number
-                    };
-                    if (!seenNames.has(user.name)) {
-                        seenNames.add(user.name);
+                    const commit = edge.node.commit;
+                    const linkedUser = ((_a = commit.author) === null || _a === void 0 ? void 0 : _a.user) || ((_b = commit.committer) === null || _b === void 0 ? void 0 : _b.user);
+                    // Fall back to the raw author/committer actor for the display name +
+                    // the email that will be surfaced when no GitHub user is linked.
+                    const rawActor = commit.author || commit.committer || {};
+                    const isLinked = Boolean(linkedUser === null || linkedUser === void 0 ? void 0 : linkedUser.databaseId);
+                    const user = Object.assign({ name: (linkedUser === null || linkedUser === void 0 ? void 0 : linkedUser.login) || rawActor.name || rawActor.email || '', id: (linkedUser === null || linkedUser === void 0 ? void 0 : linkedUser.databaseId) || 0, pullRequestNo: github_1.context.issue.number }, (isLinked ? {} : { email: rawActor.email }));
+                    // Dedup by (id, email) so two commits from the same unlinked address
+                    // collapse but two different unlinked addresses don't.
+                    const key = `${user.id}:${(_c = user.email) !== null && _c !== void 0 ? _c : ''}:${user.name}`;
+                    if (!seenKeys.has(key)) {
+                        seenKeys.add(key);
                         committers.push(user);
                     }
                 }
@@ -30316,14 +30321,6 @@ function getCommitters() {
         }
     });
 }
-function extractUserFromCommit(commit) {
-    var _a, _b;
-    return (((_a = commit.author) === null || _a === void 0 ? void 0 : _a.user) ||
-        ((_b = commit.committer) === null || _b === void 0 ? void 0 : _b.user) ||
-        commit.author ||
-        commit.committer ||
-        {});
-}
 
 
 /***/ }),
@@ -30995,10 +30992,7 @@ function renderPending(mode, committerMap) {
         text += '<br/>';
     }
     if (committerMap.unknown.length > 0) {
-        const seem = committerMap.unknown.length > 1 ? 'seem' : 'seems';
-        const names = committerMap.unknown.map(c => c.name).join(', ');
-        text += `**${names}** ${seem} not to be a GitHub user.`;
-        text += ` You need a GitHub account to be able to sign the ${mode.label}. If you have already a GitHub account, please [add the email address used for this commit to your account](https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user).<br/>`;
+        text += renderUnlinkedCommitBlock(mode, committerMap.unknown);
     }
     if (input.suggestRecheck()) {
         text +=
@@ -31010,6 +31004,51 @@ function renderPending(mode, committerMap) {
 function botSignature(mode) {
     return `<sub>Posted by the **${mode.botName}**.</sub>`;
 }
+/**
+ * Renders the "commit author email isn't linked to a GitHub account" block.
+ * Shown both inline (when mixed with signed/unsigned committers) and as the
+ * sole body (when every committer is unlinked — in which case this is the
+ * only actionable thing in the comment).
+ */
+function renderUnlinkedCommitBlock(mode, unlinked) {
+    const plural = unlinked.length > 1;
+    const verb = plural ? 'were' : 'was';
+    const commits = plural ? 'commits' : 'commit';
+    // Render each unlinked identity as "name <email>" when we have an email to
+    // show, otherwise just the name. Wrap email in backticks so Markdown does
+    // not interpret it as a mailto: auto-link.
+    const identityLines = unlinked
+        .map(c => {
+        const display = c.email && c.email !== c.name ? `${c.name} \`<${c.email}>\`` : c.name;
+        return `- ${display}`;
+    })
+        .join('\n');
+    return `
+
+> [!WARNING]
+> ${unlinked.length} ${commits} in this PR ${verb} authored by an email address that is not linked to any GitHub user, so we cannot tell whether the author has signed the ${mode.label}.
+>
+> Unlinked author${plural ? 's' : ''}:
+>
+> ${identityLines.replace(/\n/g, '\n> ')}
+>
+> **To unblock this PR, do one of the following:**
+>
+> 1. **Link the email to your GitHub account** (recommended). Add each address above at [github.com/settings/emails](https://github.com/settings/emails), then push another commit (or comment \`recheck\`) so this check re-runs. See [why commits are not linked to a user](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user#commits-are-not-linked-to-any-user) for details.
+>
+> 2. **Rewrite the commits** to use an email that is already linked to your GitHub account:
+>
+>    \`\`\`bash
+>    # Set the correct email locally (one-off, for this repo):
+>    git config user.email you@example.com
+>    # Rewrite every commit on this branch with the corrected identity:
+>    git rebase -i --root --exec 'git commit --amend --reset-author --no-edit'
+>    git push --force-with-lease
+>    \`\`\`
+>
+>    After the push, comment \`recheck\` on this PR (or just re-push) to re-run the check.
+<br/>`;
+}
 
 
 /***/ }),

src/graphql.ts

@@ -66,7 +66,7 @@ query($owner:String! $name:String! $number:Int! $cursor:String){
 
 export default async function getCommitters(): Promise<Committer[]> {
   try {
-    const seenNames = new Set<string>()
+    const seenKeys = new Set<string>()
     const committers: Committer[] = []
     let cursor: string | null = null
     let hasNextPage = true
@@ -81,14 +81,23 @@ export default async function getCommitters(): Promise<Committer[]> {
 
       const page = response.repository.pullRequest.commits
       for (const edge of page.edges) {
-        const actor = extractUserFromCommit(edge.node.commit)
+        const commit = edge.node.commit
+        const linkedUser = commit.author?.user || commit.committer?.user
+        // Fall back to the raw author/committer actor for the display name +
+        // the email that will be surfaced when no GitHub user is linked.
+        const rawActor = commit.author || commit.committer || {}
+        const isLinked = Boolean(linkedUser?.databaseId)
         const user: Committer = {
-          name: actor.login || actor.name || '',
-          id: actor.databaseId || 0,
-          pullRequestNo: context.issue.number
+          name: linkedUser?.login || rawActor.name || rawActor.email || '',
+          id: linkedUser?.databaseId || 0,
+          pullRequestNo: context.issue.number,
+          ...(isLinked ? {} : { email: rawActor.email })
         }
-        if (!seenNames.has(user.name)) {
-          seenNames.add(user.name)
+        // Dedup by (id, email) so two commits from the same unlinked address
+        // collapse but two different unlinked addresses don't.
+        const key = `${user.id}:${user.email ?? ''}:${user.name}`
+        if (!seenKeys.has(key)) {
+          seenKeys.add(key)
           committers.push(user)
         }
       }
@@ -103,13 +112,3 @@ export default async function getCommitters(): Promise<Committer[]> {
     )
   }
 }
-
-function extractUserFromCommit(
-  commit: GraphQLCommit
-): GraphQLUser & GraphQLActor {
-  return (commit.author?.user ||
-    commit.committer?.user ||
-    commit.author ||
-    commit.committer ||
-    {}) as GraphQLUser & GraphQLActor
-}

src/interfaces.ts

@@ -6,6 +6,13 @@ export interface Committer {
   name: string
   id: number
   pullRequestNo?: number | undefined
+  /**
+   * Commit-author email. Present only when the GraphQL lookup could not map
+   * the commit to a GitHub user (i.e. when this committer ends up in
+   * CommitterMap.unknown). Surfaced to the contributor in the PR comment so
+   * they know which specific email address to link or rewrite.
+   */
+  email?: string | undefined
 }
 
 /**

src/pullrequest/pullRequestCommentContent.ts

@@ -1,4 +1,4 @@
-import { CommitterMap } from '../interfaces'
+import { Committer, CommitterMap } from '../interfaces'
 import * as input from '../shared/getInputs'
 import { getPrSignComment } from '../shared/pr-sign-comment'
 
@@ -70,10 +70,7 @@ function renderPending(mode: ModeText, committerMap: CommitterMap): string {
   }
 
   if (committerMap.unknown.length > 0) {
-    const seem = committerMap.unknown.length > 1 ? 'seem' : 'seems'
-    const names = committerMap.unknown.map(c => c.name).join(', ')
-    text += `**${names}** ${seem} not to be a GitHub user.`
-    text += ` You need a GitHub account to be able to sign the ${mode.label}. If you have already a GitHub account, please [add the email address used for this commit to your account](https://help.github.com/articles/why-are-my-commits-linked-to-the-wrong-user/#commits-are-not-linked-to-any-user).<br/>`
+    text += renderUnlinkedCommitBlock(mode, committerMap.unknown)
   }
 
   if (input.suggestRecheck()) {
@@ -88,3 +85,55 @@ function renderPending(mode: ModeText, committerMap: CommitterMap): string {
 function botSignature(mode: ModeText): string {
   return `<sub>Posted by the **${mode.botName}**.</sub>`
 }
+
+/**
+ * Renders the "commit author email isn't linked to a GitHub account" block.
+ * Shown both inline (when mixed with signed/unsigned committers) and as the
+ * sole body (when every committer is unlinked — in which case this is the
+ * only actionable thing in the comment).
+ */
+function renderUnlinkedCommitBlock(
+  mode: ModeText,
+  unlinked: Committer[]
+): string {
+  const plural = unlinked.length > 1
+  const verb = plural ? 'were' : 'was'
+  const commits = plural ? 'commits' : 'commit'
+
+  // Render each unlinked identity as "name <email>" when we have an email to
+  // show, otherwise just the name. Wrap email in backticks so Markdown does
+  // not interpret it as a mailto: auto-link.
+  const identityLines = unlinked
+    .map(c => {
+      const display =
+        c.email && c.email !== c.name ? `${c.name} \`<${c.email}>\`` : c.name
+      return `- ${display}`
+    })
+    .join('\n')
+
+  return `
+
+> [!WARNING]
+> ${unlinked.length} ${commits} in this PR ${verb} authored by an email address that is not linked to any GitHub user, so we cannot tell whether the author has signed the ${mode.label}.
+>
+> Unlinked author${plural ? 's' : ''}:
+>
+> ${identityLines.replace(/\n/g, '\n> ')}
+>
+> **To unblock this PR, do one of the following:**
+>
+> 1. **Link the email to your GitHub account** (recommended). Add each address above at [github.com/settings/emails](https://github.com/settings/emails), then push another commit (or comment \`recheck\`) so this check re-runs. See [why commits are not linked to a user](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/troubleshooting-commits/why-are-my-commits-linked-to-the-wrong-user#commits-are-not-linked-to-any-user) for details.
+>
+> 2. **Rewrite the commits** to use an email that is already linked to your GitHub account:
+>
+>    \`\`\`bash
+>    # Set the correct email locally (one-off, for this repo):
+>    git config user.email you@example.com
+>    # Rewrite every commit on this branch with the corrected identity:
+>    git rebase -i --root --exec 'git commit --amend --reset-author --no-edit'
+>    git push --force-with-lease
+>    \`\`\`
+>
+>    After the push, comment \`recheck\` on this PR (or just re-push) to re-run the check.
+<br/>`
+}