git-commit-guard 0.20.1__tar.gz → 0.21.0__tar.gz

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/.github/workflows/lint-commits.yml

@@ -22,6 +22,6 @@ jobs:
           key: nltk-averaged-perceptron-tagger-punkt
       - name: Lint commits
         # yamllint disable-line rule:line-length
-        uses: benner/commit-guard@cab0d35c41a3f99fc5f61895f491d0ce3f5aff1c  # v0.20.0
+        uses: benner/commit-guard@87889d2f3a1fb68bfa55dbbab28c96def415341e  # v0.20.1
         with:
           range: origin/${{ github.base_ref }}..HEAD

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-commit-guard
-Version: 0.20.1
+Version: 0.21.0
 Summary: Opinionated conventional commit message linter with imperative mood detection
 Project-URL: Homepage, https://github.com/benner/commit-guard
 Project-URL: Repository, https://github.com/benner/commit-guard
@@ -21,18 +21,32 @@ Description-Content-Type: text/markdown
 
 # commit-guard
 
+<!-- markdownlint-disable MD013 -->
+[![PyPI version](https://img.shields.io/pypi/v/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![CI](https://github.com/benner/commit-guard/actions/workflows/test.yml/badge.svg)](https://github.com/benner/commit-guard/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
+<!-- markdownlint-restore -->
+
 Opinionated conventional commit message linter with imperative mood detection.
 
-Unlike regular expression only tools, commit-guard uses
-NLP (nltk POS tagging) to verify that commit descriptions start with an
-imperative verb.
+## Why commit-guard?
+
+* **NLP imperative detection.** Descriptions must start with an imperative
+  verb, verified via nltk POS tagging — not a hand-coded regex of "bad"
+  words.
+* **Signature verification without a local keyring.** Resolves the commit
+  author via the GitHub API and verifies GPG/SSH against their published
+  `.gpg`/`.keys` — no per-runner key management.
+* **Strict by default.** Subject format, body, trailers, `Signed-off-by`,
+  and signature all enforced out of the box; opt out with `--disable`.
 
 ## Example
 
 ```bash
 $ commit-guard
   ✗ [subject] subject does not match 'type(scope): description': WIP
-  ✗ [signed-off] missing 'Signed-off-by' trailer
+  ✗ [signed-off] missing 'Signed-off-by' trailer — use 'git commit -s'
   ✗ [signature] commit is not signed (GPG/SSH)
 ```
 
@@ -94,12 +108,12 @@ commit-guard --disable body,signed-off,signature
 Available checks:
 
 * `subject` - Format matches `type(scope): description`, valid type,
-    lowercase start, no trailing `.` `!` `?` or space, max 72 chars
+  lowercase start, no trailing `.` `!` `?` or space, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
 * `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature via the GitHub Commits API or
-    public key lookup
+  public key lookup
 
 ### Subject length
 
@@ -296,7 +310,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.20.1
+- uses: benner/commit-guard@v0.21.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -380,7 +394,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.20.1
+  - uses: benner/commit-guard@v0.21.0
 ```
 
 Check all commits in a pull request:
@@ -396,7 +410,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -404,7 +418,7 @@ jobs:
 Check a specific commit SHA (mirrors the positional CLI argument):
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           rev: ${{ github.sha }}
 ```
@@ -422,7 +436,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -442,7 +456,7 @@ jobs:
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -458,7 +472,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.21.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/README.md

@@ -1,17 +1,31 @@
 # commit-guard
 
+<!-- markdownlint-disable MD013 -->
+[![PyPI version](https://img.shields.io/pypi/v/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/git-commit-guard.svg)](https://pypi.org/project/git-commit-guard/)
+[![CI](https://github.com/benner/commit-guard/actions/workflows/test.yml/badge.svg)](https://github.com/benner/commit-guard/actions/workflows/test.yml)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/)
+<!-- markdownlint-restore -->
+
 Opinionated conventional commit message linter with imperative mood detection.
 
-Unlike regular expression only tools, commit-guard uses
-NLP (nltk POS tagging) to verify that commit descriptions start with an
-imperative verb.
+## Why commit-guard?
+
+* **NLP imperative detection.** Descriptions must start with an imperative
+  verb, verified via nltk POS tagging — not a hand-coded regex of "bad"
+  words.
+* **Signature verification without a local keyring.** Resolves the commit
+  author via the GitHub API and verifies GPG/SSH against their published
+  `.gpg`/`.keys` — no per-runner key management.
+* **Strict by default.** Subject format, body, trailers, `Signed-off-by`,
+  and signature all enforced out of the box; opt out with `--disable`.
 
 ## Example
 
 ```bash
 $ commit-guard
   ✗ [subject] subject does not match 'type(scope): description': WIP
-  ✗ [signed-off] missing 'Signed-off-by' trailer
+  ✗ [signed-off] missing 'Signed-off-by' trailer — use 'git commit -s'
   ✗ [signature] commit is not signed (GPG/SSH)
 ```
 
@@ -73,12 +87,12 @@ commit-guard --disable body,signed-off,signature
 Available checks:
 
 * `subject` - Format matches `type(scope): description`, valid type,
-    lowercase start, no trailing `.` `!` `?` or space, max 72 chars
+  lowercase start, no trailing `.` `!` `?` or space, max 72 chars
 * `imperative` - First word is an imperative verb (for example `add` not `added`)
 * `body` - Blank line separates subject from body, and body is non-empty
 * `signed-off` - `Signed-off-by:` trailer exists
 * `signature` - Verify GPG or SSH signature via the GitHub Commits API or
-    public key lookup
+  public key lookup
 
 ### Subject length
 
@@ -275,7 +289,7 @@ COMMIT_GUARD_GIT_TIMEOUT=30 commit-guard --range origin/main..HEAD
 In GitHub Actions, set it at the step or job level:
 
 ```yaml
-- uses: benner/commit-guard@v0.20.1
+- uses: benner/commit-guard@v0.21.0
   env:
     COMMIT_GUARD_GIT_TIMEOUT: 30
   with:
@@ -359,7 +373,7 @@ steps:
   - uses: actions/checkout@v4
     with:
       fetch-depth: 0
-  - uses: benner/commit-guard@v0.20.1
+  - uses: benner/commit-guard@v0.21.0
 ```
 
 Check all commits in a pull request:
@@ -375,7 +389,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
 ```
@@ -383,7 +397,7 @@ jobs:
 Check a specific commit SHA (mirrors the positional CLI argument):
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           rev: ${{ github.sha }}
 ```
@@ -401,7 +415,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature
@@ -421,7 +435,7 @@ jobs:
 When `output-file` is set the action exposes the path as an output:
 
 ```yaml
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -437,7 +451,7 @@ Add to your `.pre-commit-config.yaml`:
 ---
 repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.21.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/docs/index.html

@@ -115,7 +115,7 @@
       .hero-terminal pre {
         margin: 0;
         font-size: 0.95rem;
-        width: 64ch;
+        width: 80ch;
         height: 12em;
         overflow: hidden;
       }
@@ -291,12 +291,10 @@
         <h1>commit-guard</h1>
         <p>Conventional commit linting with imperative mood detection.</p>
         <div class="hero-terminal">
-          <pre><code id="hero-code">$ commit-guard --range origin/main..HEAD
-<span class="c-dim">abc1234</span> feat: add user authentication
-  <span class="c-green">✓</span> all checks passed
-<span class="c-dim">def5678</span> wip: still working
-  <span class="c-red">✗</span> <span class="c-dim">[subject]</span> unknown type: wip
-  <span class="c-red">✗</span> <span class="c-dim">[body]</span> missing body</code></pre>
+          <pre><code id="hero-code">$ commit-guard
+  <span class="c-red">✗</span> <span class="c-dim">[subject]</span> subject does not match 'type(scope): description': WIP
+  <span class="c-red">✗</span> <span class="c-dim">[signed-off]</span> missing 'Signed-off-by' trailer — use 'git commit -s'
+  <span class="c-red">✗</span> <span class="c-dim">[signature]</span> commit is not signed (GPG/SSH)</code></pre>
         </div>
         <div class="hero-dots">
           <button class="hero-dot" data-i="0"></button>
@@ -305,6 +303,28 @@
         </div>
       </section>
 
+      <section id="why">
+        <h2>Why commit-guard? <a href="#why" class="anchor">#</a></h2>
+        <ul>
+          <li>
+            <strong>NLP imperative detection.</strong> Descriptions must start
+            with an imperative verb, verified via nltk POS tagging — not a
+            hand-coded regex of "bad" words.
+          </li>
+          <li>
+            <strong>Signature verification without a local keyring.</strong>
+            Resolves the commit author via the GitHub API and verifies GPG/SSH
+            against their published <code>.gpg</code>/<code>.keys</code> — no
+            per-runner key management.
+          </li>
+          <li>
+            <strong>Strict by default.</strong> Subject format, body, trailers,
+            <code>Signed-off-by</code>, and signature all enforced out of the
+            box; opt out with <code>--disable</code>.
+          </li>
+        </ul>
+      </section>
+
       <section id="install">
         <h2>Install <a href="#install" class="anchor">#</a></h2>
         <div class="install-tabs">
@@ -538,13 +558,13 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: benner/commit-guard@v0.20.1
+      - uses: benner/commit-guard@v0.21.0
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
           disable: signed-off,signature</code></pre>
 
         <p>Check a specific commit SHA:</p>
-        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.20.1
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.21.0
         with:
           rev: ${{ github.sha }}</code></pre>
 
@@ -563,7 +583,7 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
           When <code>output-file</code> is set the action exposes the path as
           a step output, making JSONL results available to subsequent steps:
         </p>
-        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.20.1
+        <pre><code class="language-yaml">      - uses: benner/commit-guard@v0.21.0
         id: cg
         with:
           range: ${{ env.PR_BASE }}..${{ env.PR_HEAD }}
@@ -576,7 +596,7 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
         <p>Add to <code>.pre-commit-config.yaml</code>:</p>
         <pre><code class="language-yaml">repos:
   - repo: https://github.com/benner/commit-guard
-    rev: v0.20.1
+    rev: v0.21.0
     hooks:
       - id: commit-guard
       - id: commit-guard-signature</code></pre>
@@ -596,16 +616,16 @@ require-subject-pattern = "[A-Z]+-[0-9]+"</code></pre>
       const EXAMPLES = [
         [
           ["$ commit-guard\n  ", null],
-          ["✗", "c-red"], [" [subject]", "c-dim"], [" unknown type: wip\n  ", null],
-          ["✗", "c-red"], [" [body]",    "c-dim"], [" missing body\n  ", null],
-          ["✗", "c-red"], [" [imperative]", "c-dim"], [" got 'added', want imperative verb", null],
+          ["✗", "c-red"], [" [subject]", "c-dim"], [" subject does not match 'type(scope): description': WIP\n  ", null],
+          ["✗", "c-red"], [" [signed-off]", "c-dim"], [" missing 'Signed-off-by' trailer — use 'git commit -s'\n  ", null],
+          ["✗", "c-red"], [" [signature]", "c-dim"], [" commit is not signed (GPG/SSH)", null],
         ],
         [
           ["$ commit-guard --range origin/main..HEAD\n", null],
           ["abc1234", "c-dim"], [" feat: add user authentication\n  ", null],
           ["✓", "c-green"], [" all checks passed\n", null],
-          ["def5678", "c-dim"], [" wip: still working\n  ", null],
-          ["✗", "c-red"], [" [subject]", "c-dim"], [" unknown type: wip\n  ", null],
+          ["def5678", "c-dim"], [" chore: added logging\n  ", null],
+          ["✗", "c-red"], [" [imperative]", "c-dim"], [" expected imperative verb, got 'added' (non-imperative suffix)\n  ", null],
           ["✗", "c-red"], [" [body]",    "c-dim"], [" missing body", null],
         ],
         [

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/src/git_commit_guard/__init__.py

@@ -11,6 +11,7 @@ import urllib.request
 from argparse import ArgumentParser
 from dataclasses import dataclass, field
 from enum import StrEnum
+from http import HTTPStatus
 from pathlib import Path
 
 import nltk
@@ -150,6 +151,12 @@ def _download_if_missing(resource):
         nltk.download(resource.rsplit("/", maxsplit=1)[-1], quiet=True)
 
 
+def _format_allowed_hint(allowed, kind):
+    if len(allowed) <= len(TYPES):
+        return f"(allowed: {', '.join(sorted(allowed))})"
+    return f"(see configured {kind})"
+
+
 def _strip_comments(message):
     return "\n".join(
         line for line in message.split("\n") if not line.lstrip().startswith("#")
@@ -177,13 +184,16 @@ def check_subject(  # noqa: PLR0913 Too many arguments in function definition (9
         return None
 
     if m.group("type") not in allowed_types:
-        result.error(f"unknown type: {m.group('type')}", check=Check.SUBJECT)
+        bad_type = m.group("type")
+        hint = _format_allowed_hint(allowed_types, "types")
+        result.error(f"unknown type: {bad_type} {hint}", check=Check.SUBJECT)
 
     scope = m.group("scope")
     if require_scope and scope is None:
         result.error("scope is required", check=Check.SUBJECT)
     if allowed_scopes and scope is not None and scope not in allowed_scopes:
-        result.error(f"unknown scope: {scope}", check=Check.SUBJECT)
+        hint = _format_allowed_hint(allowed_scopes, "scopes")
+        result.error(f"unknown scope: {scope} {hint}", check=Check.SUBJECT)
 
     desc = m.group("desc")
     if require_lowercase and desc[0].isupper():
@@ -248,7 +258,10 @@ def check_body(lines, result):
 
 def check_signed_off(message, result):
     if not SIGNED_OFF_RE.search(message):
-        result.error("missing 'Signed-off-by' trailer", check=Check.SIGNED_OFF)
+        result.error(
+            "missing 'Signed-off-by' trailer — use 'git commit -s'",
+            check=Check.SIGNED_OFF,
+        )
 
 
 def check_subject_pattern(subject, pattern, result):
@@ -387,22 +400,46 @@ def _verify_ssh(rev, email, ssh_text):
         Path(signers_path).unlink(missing_ok=True)
 
 
+def _resolve_github_username(rev, email):
+    username = None
+    commits_api_404 = False
+    remote = _get_github_remote_info()
+    if remote:
+        owner, repo = remote
+        try:
+            username = _fetch_github_commit_author(owner, repo, rev)
+        except urllib.error.HTTPError as e:
+            if e.code == HTTPStatus.NOT_FOUND:
+                commits_api_404 = True
+            elif e.code in (HTTPStatus.UNAUTHORIZED, HTTPStatus.FORBIDDEN):
+                raise
+        except (urllib.error.URLError, TimeoutError):
+            pass
+    if username is None:
+        username = _parse_noreply_username(email)
+    if username is None:
+        username = _fetch_github_username(email)
+    return username, commits_api_404
+
+
+def _author_not_found_message(commits_api_404):
+    had_token = bool(os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN"))
+    if commits_api_404 and not had_token:
+        return (
+            "commit author not found on GitHub — if the repo is private, "
+            "set GITHUB_TOKEN in the workflow step "
+            "(env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }})"
+        )
+    return "commit author not found on GitHub — cannot verify signature"
+
+
 def check_signature(rev, result):
     try:
         email = _get_author_email(rev)
-        username = None
-        remote = _get_github_remote_info()
-        if remote:
-            owner, repo = remote
-            with contextlib.suppress(urllib.error.URLError, TimeoutError):
-                username = _fetch_github_commit_author(owner, repo, rev)
-        if username is None:
-            username = _parse_noreply_username(email)
-        if username is None:
-            username = _fetch_github_username(email)
+        username, commits_api_404 = _resolve_github_username(rev, email)
         if username is None:
             result.error(
-                "commit author not found on GitHub — cannot verify signature",
+                _author_not_found_message(commits_api_404),
                 check=Check.SIGNATURE,
             )
             return
@@ -419,6 +456,24 @@ def check_signature(rev, result):
             "git operation timed out — cannot verify signature",
             check=Check.SIGNATURE,
         )
+    except urllib.error.HTTPError as e:
+        if e.code == HTTPStatus.UNAUTHORIZED:
+            result.error(
+                "GitHub API rejected token (HTTP 401) — "
+                "GITHUB_TOKEN may be invalid or expired",
+                check=Check.SIGNATURE,
+            )
+        elif e.code == HTTPStatus.FORBIDDEN:
+            result.error(
+                "GitHub API forbidden (HTTP 403) — GITHUB_TOKEN may lack "
+                "'repo' scope, or you are unauthenticated and rate-limited",
+                check=Check.SIGNATURE,
+            )
+        else:
+            result.error(
+                f"GitHub API error (HTTP {e.code}) — cannot verify signature",
+                check=Check.SIGNATURE,
+            )
     except (urllib.error.URLError, TimeoutError):
         result.error(
             "GitHub API unreachable — cannot verify signature",

{git_commit_guard-0.20.1 → git_commit_guard-0.21.0}/tests/test_git_commit_guard.py

@@ -124,6 +124,25 @@ class TestCheckSubject:
         check_subject("unknown: add thing", r)
         assert not r.ok
 
+    def test_unknown_type_with_default_lists_all_allowed(self):
+        r = Result()
+        check_subject("unknown: add thing", r)
+        assert any(
+            "allowed: " in m and "feat" in m and "fix" in m for _, _, m in r.errors
+        )
+
+    def test_unknown_type_with_smaller_set_lists_them(self):
+        r = Result()
+        check_subject("foo: add thing", r, allowed_types=frozenset({"feat", "fix"}))
+        assert any("allowed: feat, fix" in m for _, _, m in r.errors)
+
+    def test_unknown_type_with_larger_than_default_points_at_config(self):
+        r = Result()
+        oversized = frozenset({f"t{i}" for i in range(20)})
+        check_subject("foo: add thing", r, allowed_types=oversized)
+        assert any("see configured types" in m for _, _, m in r.errors)
+        assert not any("allowed:" in m for _, _, m in r.errors)
+
     def test_uppercase_description(self):
         r = Result()
         check_subject("fix: Add token", r)
@@ -184,6 +203,22 @@ class TestCheckSubject:
         check_subject("fix(api): add token", r, allowed_scopes=frozenset(["auth"]))
         assert not r.ok
 
+    def test_unknown_scope_with_small_set_lists_them(self):
+        r = Result()
+        check_subject(
+            "fix(api): add token",
+            r,
+            allowed_scopes=frozenset({"auth", "db"}),
+        )
+        assert any("allowed: auth, db" in m for _, _, m in r.errors)
+
+    def test_unknown_scope_with_larger_than_default_points_at_config(self):
+        r = Result()
+        oversized = frozenset({f"s{i}" for i in range(20)})
+        check_subject("fix(foo): add token", r, allowed_scopes=oversized)
+        assert any("see configured scopes" in m for _, _, m in r.errors)
+        assert not any("allowed:" in m for _, _, m in r.errors)
+
     def test_no_scope_with_allowlist_passes(self):
         r = Result()
         check_subject("fix: add token", r, allowed_scopes=frozenset(["auth"]))
@@ -325,6 +360,11 @@ class TestCheckSignedOff:
         check_signed_off("fix: add thing\n\nbody", r)
         assert not r.ok
 
+    def test_missing_message_hints_at_git_commit_dash_s(self):
+        r = Result()
+        check_signed_off("fix: add thing\n\nbody", r)
+        assert any("git commit -s" in m for _, _, m in r.errors)
+
     def test_malformed_no_email(self):
         r = Result()
         check_signed_off("fix: add thing\n\nSigned-off-by: John Doe", r)
@@ -816,6 +856,157 @@ class TestCheckSignature:
         assert not r.ok
         assert any("not found on GitHub" in msg for _, _, msg in r.errors)
 
+    def test_commits_api_404_without_token_hints_at_token(self):
+        r = Result()
+        env = {
+            k: v for k, v in os.environ.items() if k not in ("GITHUB_TOKEN", "GH_TOKEN")
+        }
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=404, msg="Not Found", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value=None),
+            patch.dict("os.environ", env, clear=True),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("set GITHUB_TOKEN" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_404_with_token_keeps_generic_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=404, msg="Not Found", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value=None),
+            patch.dict("os.environ", {"GITHUB_TOKEN": "x"}, clear=False),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert not any("set GITHUB_TOKEN" in msg for _, _, msg in r.errors)
+        assert any("cannot verify signature" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_non_404_http_error_falls_through(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=500, msg="Server Error", hdrs=None, fp=None
+                ),
+            ),
+            patch("git_commit_guard._fetch_github_username", return_value="emailuser"),
+            patch("git_commit_guard._fetch_github_keys", return_value=("GPG KEY", "")),
+            patch("git_commit_guard._verify_gpg", return_value=True),
+        ):
+            check_signature("abc123", r)
+        assert r.ok
+
+    def test_commits_api_401_surfaces_token_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=401, msg="Unauthorized", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("rejected token (HTTP 401)" in msg for _, _, msg in r.errors)
+
+    def test_commits_api_403_surfaces_token_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="user@example.com"
+            ),
+            patch(
+                "git_commit_guard._get_github_remote_info",
+                return_value=("owner", "repo"),
+            ),
+            patch(
+                "git_commit_guard._fetch_github_commit_author",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=403, msg="Forbidden", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("forbidden (HTTP 403)" in msg for _, _, msg in r.errors)
+
+    def test_search_api_403_surfaces_rate_limit_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="corp@example.com"
+            ),
+            patch("git_commit_guard._get_github_remote_info", return_value=None),
+            patch(
+                "git_commit_guard._fetch_github_username",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=403, msg="Forbidden", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("forbidden (HTTP 403)" in msg for _, _, msg in r.errors)
+
+    def test_other_http_error_uses_generic_http_message(self):
+        r = Result()
+        with (
+            patch(
+                "git_commit_guard._get_author_email", return_value="corp@example.com"
+            ),
+            patch("git_commit_guard._get_github_remote_info", return_value=None),
+            patch(
+                "git_commit_guard._fetch_github_username",
+                side_effect=urllib.error.HTTPError(
+                    url="", code=500, msg="Server Error", hdrs=None, fp=None
+                ),
+            ),
+        ):
+            check_signature("abc123", r)
+        assert not r.ok
+        assert any("GitHub API error (HTTP 500)" in msg for _, _, msg in r.errors)
+
     def test_url_error_fails(self):
         r = Result()
         with patch(