Improve GitHub authentication errors

ddev/changelog.d/24502.fixed

@@ -0,0 +1 @@
+Show actionable guidance when GitHub rejects ddev's configured token.

ddev/src/ddev/cli/__init__.py

@@ -9,7 +9,7 @@
 
 from ddev._version import __version__
 from ddev.cli import upgrade_check
-from ddev.cli.application import Application
+from ddev.cli.application import Application, DdevGroup
 from ddev.cli.ci import ci
 from ddev.cli.clean import clean
 from ddev.cli.config import config
@@ -27,9 +27,14 @@
 from ddev.plugin import specs
 from ddev.utils.ci import running_in_ci
 from ddev.utils.fs import Path
+from ddev.utils.github_errors import GitHubAuthenticationError
 
 
-@click.group(context_settings={'help_option_names': ['-h', '--help']}, invoke_without_command=True)
+def _display_registered_exception(app: Application, error: Exception) -> None:
+    app.display_error(str(error))
+
+
+@click.group(cls=DdevGroup, context_settings={'help_option_names': ['-h', '--help']}, invoke_without_command=True)
 @click.option('--core', '-c', is_flag=True, help='Work on `integrations-core`.')
 @click.option('--extras', '-e', is_flag=True, help='Work on `integrations-extras`.')
 @click.option('--marketplace', '-m', is_flag=True, help='Work on `marketplace`.')
@@ -93,6 +98,7 @@ def ddev(
         interactive = not running_in_ci()
 
     app = Application(ctx.exit, verbose - quiet, color, interactive)
+    app.register_exception_handler(GitHubAuthenticationError, _display_registered_exception)
 
     if config_file:
         app.config_file.path = Path(config_file).resolve()

ddev/src/ddev/cli/application.py

@@ -6,10 +6,12 @@
 import logging
 import os
 from collections import defaultdict
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from functools import cached_property
 from typing import TYPE_CHECKING, cast
 
+import click
+
 from ddev.cli.terminal import Terminal
 from ddev.config.constants import AppEnvVars, ConfigEnvVars, VerbosityLevels
 from ddev.config.file import ConfigFileWithOverrides, RootConfig
@@ -20,7 +22,23 @@
 from ddev.utils.platform import Platform
 
 if TYPE_CHECKING:
-    from typing import Any, Callable, NoReturn
+    from typing import Any, NoReturn
+
+
+type ExceptionHandler = Callable[[Application, Exception], None]
+
+
+class DdevGroup(click.Group):
+    """Root command group that renders registered exceptions through the application."""
+
+    def invoke(self, ctx: click.Context) -> Any:
+        try:
+            return super().invoke(ctx)
+        except Exception as error:
+            app = ctx.obj
+            if isinstance(app, Application) and app.handle_exception(error):
+                ctx.exit(1)
+            raise
 
 
 class AppLoggingHandler(logging.Handler):
@@ -57,6 +75,8 @@ def __init__(self, exit_func: Callable[[int], NoReturn], *args, **kwargs):
         # TODO: remove this when the old CLI is gone
         self.__config: dict[str, Any] = {}
 
+        self.__exception_handlers: dict[type[Exception], ExceptionHandler] = {}
+
     @property
     def config(self) -> RootConfig:
         return self.config_file.combined_model
@@ -116,6 +136,22 @@ def abort(self, text: str = '', code: int = 1, **kwargs: Any) -> NoReturn:
             self.display_error(text, **kwargs)
         self.__exit_func(code)
 
+    def register_exception_handler(
+        self,
+        exception_type: type[Exception],
+        handler: ExceptionHandler,
+    ) -> None:
+        """Register an internal CLI handler for an exception type."""
+        self.__exception_handlers[exception_type] = handler
+
+    def handle_exception(self, error: Exception) -> bool:
+        """Render an exception with its nearest registered type."""
+        for exception_type in type(error).mro():
+            if handler := self.__exception_handlers.get(exception_type):
+                handler(self, error)
+                return True
+        return False
+
     def annotate_error(self, file: str, message: str, line: int = 1) -> None:
         """Emit a GitHub Actions ``error`` workflow annotation; no-op outside CI."""
         self._emit_github_annotation(AnnotationLevel.ERROR, file, message, line)

ddev/src/ddev/cli/release/port_commit_workflow.py

@@ -424,11 +424,6 @@ def _resolve_pr_to_commit(app: Application, pr_number: int, *, dry_run: bool) ->
         status = exc.response.status_code
         if status == 404:
             raise _PRNotFound(str(pr_number)) from exc
-        if status in (401, 403):
-            app.abort(
-                f'GitHub denied the request for PR #{pr_number} (HTTP {status}). '
-                'Check that `github.token` is set and has `repo` scope.'
-            )
         app.abort(f'Failed to fetch PR #{pr_number} from GitHub: {exc}.')
     except (httpx.HTTPError, ValidationError) as exc:
         app.abort(f'Failed to fetch PR #{pr_number} from GitHub: {exc}.')

ddev/src/ddev/utils/github.py

@@ -8,6 +8,8 @@
 from time import time
 from typing import TYPE_CHECKING, overload
 
+from ddev.utils.github_errors import GITHUB_AUTHENTICATION_STATUS_CODES, GitHubAuthenticationError
+
 if TYPE_CHECKING:
     from typing import Any, Literal
 
@@ -305,7 +307,7 @@ def __api_get(self, *args, **kwargs):
         return self.__api_call('get', *args, **kwargs)
 
     def __api_call(self, method, *args, **kwargs):
-        from httpx import HTTPError
+        from httpx import HTTPError, HTTPStatusError
 
         retry_wait = 2
         while True:
@@ -314,7 +316,7 @@ def __api_call(self, method, *args, **kwargs):
 
                 # https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limiting
                 # https://docs.github.com/en/rest/guides/best-practices-for-integrators?apiVersion=2022-11-28#dealing-with-rate-limits
-                if response.status_code == 403 and response.headers['X-RateLimit-Remaining'] == '0':  # noqa: PLR2004
+                if response.status_code == 403 and response.headers.get('X-RateLimit-Remaining') == '0':  # noqa: PLR2004
                     self.__status.wait_for(
                         float(response.headers['X-RateLimit-Reset']) - time() + 1,
                         context='GitHub API rate limit reached',
@@ -325,5 +327,10 @@ def __api_call(self, method, *args, **kwargs):
                 retry_wait *= 2
                 continue
 
-            response.raise_for_status()
+            try:
+                response.raise_for_status()
+            except HTTPStatusError as e:
+                if e.response.status_code in GITHUB_AUTHENTICATION_STATUS_CODES:
+                    raise GitHubAuthenticationError.from_http_status_error(e) from e
+                raise
             return response

ddev/src/ddev/utils/github_async/client.py

@@ -17,6 +17,7 @@
 import httpx
 from pydantic import BaseModel, ConfigDict, Field
 
+from ddev.utils.github_errors import GITHUB_AUTHENTICATION_STATUS_CODES, GitHubAuthenticationError
 from ddev.utils.rate_limiting import NULL_SNAPSHOT, BudgetSnapshot, InstrumentedAsyncLimiter
 
 from .defaults import default_github_rate_limiter
@@ -236,8 +237,14 @@ async def _request(
                     # the action. (Transport errors are never retried, and are not caught here: after
                     # one we cannot know whether the action executed.) Give up on the last attempt or
                     # on a non-rate-limit status, which waiting cannot fix.
-                    if attempt == self._max_rate_limit_retries or not self._is_rate_limit_response(exc.response):
-                        raise
+                    is_rate_limit_response = self._is_rate_limit_response(exc.response)
+                    if is_rate_limit_response:
+                        if attempt == self._max_rate_limit_retries:
+                            raise
+                        continue
+                    if exc.response.status_code in GITHUB_AUTHENTICATION_STATUS_CODES:
+                        raise GitHubAuthenticationError.from_http_status_error(exc) from exc
+                    raise
         raise RuntimeError("unreachable: the retry loop always returns or raises")  # pragma: no cover
 
     async def _paginated_request(

ddev/src/ddev/utils/github_errors.py

@@ -0,0 +1,34 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+from __future__ import annotations
+
+import httpx
+
+GITHUB_AUTHENTICATION_STATUS_CODES = frozenset((401, 403))
+
+
+def github_authentication_error_message(status_code: int, *, action: str = 'requested operation') -> str:
+    """Return actionable guidance for a GitHub authentication failure."""
+    return (
+        f'GitHub denied the {action} (HTTP {status_code}). The configured token may be invalid, expired, '
+        'or missing required permissions. Run `ddev config set github.token` to configure a valid token.'
+    )
+
+
+class GitHubAuthenticationError(Exception):
+    """A GitHub HTTP failure caused by invalid authentication or insufficient permissions."""
+
+    def __init__(self, message: str, *, request: httpx.Request, response: httpx.Response) -> None:
+        super().__init__(message)
+        self.request = request
+        self.response = response
+
+    @classmethod
+    def from_http_status_error(cls, error: httpx.HTTPStatusError) -> GitHubAuthenticationError:
+        """Build an authentication error while retaining the original HTTP context."""
+        return cls(
+            github_authentication_error_message(error.response.status_code),
+            request=error.request,
+            response=error.response,
+        )

ddev/tests/cli/release/test_agent/test_command.py

@@ -7,6 +7,7 @@
 import pytest
 from pytest_mock import MockerFixture
 
+from ddev.utils.github_errors import GitHubAuthenticationError
 from tests.helpers.github_async import DEFAULT_DISPATCH_HTML_URL, FakeAsyncGitHubClient
 from tests.helpers.runner import CliRunner
 
@@ -18,6 +19,15 @@
 }
 
 
+def github_authentication_error() -> GitHubAuthenticationError:
+    error = httpx.HTTPStatusError(
+        'forbidden',
+        request=httpx.Request('POST', 'https://api.github.com/'),
+        response=httpx.Response(403),
+    )
+    return GitHubAuthenticationError.from_http_status_error(error)
+
+
 @pytest.fixture(autouse=True)
 def _silence_git(mocker: MockerFixture) -> None:
     """Default git mocks: `fetch_target` succeeds and `git show` returns workflow yaml."""
@@ -293,32 +303,25 @@ def test_partial_dispatch_failure_surfaces_sibling_url(
     failing_label: str,
 ) -> None:
     """When only one dispatch fails, the surviving side's URL must appear in the error message."""
-    err = httpx.HTTPStatusError(
-        'forbidden',
-        request=httpx.Request('POST', 'https://api.github.com/'),
-        response=httpx.Response(403),
-    )
+    err = github_authentication_error()
     fake_async_github.mock_response('create_workflow_dispatch', err, workflow_id=failing_workflow)
 
     result = ddev('release', 'test-agent', '--branch', '7.80.x', '--yes')
 
     assert result.exit_code != 0, result.output
     assert f'{failing_label} dispatch failed' in result.output
     assert DEFAULT_DISPATCH_HTML_URL in result.output
+    assert 'ddev config set github.token' in result.output
 
 
 def test_both_dispatches_fail_combine_messages(ddev: CliRunner, fake_async_github: FakeAsyncGitHubClient) -> None:
     """Both-fail must announce itself explicitly and surface both error reprs, not just substrings.
 
-    Asserting on `forbidden` appearing twice catches the previous regression where `add_note`
-    was used to attach the Windows error — `str(exc)` does not include notes, so the Windows
-    side was silently dropped from the abort message.
+    Asserting on the token guidance appearing twice catches the previous regression where
+    `add_note` was used to attach the Windows error — `str(exc)` does not include notes, so
+    the Windows side was silently dropped from the abort message.
     """
-    err = httpx.HTTPStatusError(
-        'forbidden',
-        request=httpx.Request('POST', 'https://api.github.com/'),
-        response=httpx.Response(403),
-    )
+    err = github_authentication_error()
     fake_async_github.mock_response('create_workflow_dispatch', err)
 
     result = ddev('release', 'test-agent', '--branch', '7.80.x', '--yes')
@@ -327,7 +330,7 @@ def test_both_dispatches_fail_combine_messages(ddev: CliRunner, fake_async_githu
     assert 'Both dispatches failed' in result.output
     assert 'Linux:' in result.output
     assert 'Windows:' in result.output
-    assert result.output.count('forbidden') == 2
+    assert result.output.count('ddev config set github.token') == 2
 
 
 def test_missing_github_token_aborts(ddev: CliRunner, mocker: MockerFixture, config_file) -> None:

ddev/tests/cli/release/test_agent/test_monitoring.py

@@ -6,6 +6,9 @@
 import importlib
 from typing import Any
 
+import httpx
+import pytest
+
 from ddev.cli.release.test_agent.dispatch import DispatchedWorkflow
 from ddev.cli.release.test_agent.monitoring import (
     JobState,
@@ -18,6 +21,7 @@
 from ddev.cli.terminal import Terminal
 from ddev.utils.github_async import GitHubResponse
 from ddev.utils.github_async.models import WorkflowJob, WorkflowJobsList, WorkflowRun
+from ddev.utils.github_errors import GitHubAuthenticationError
 from tests.helpers.github_async import FakeAsyncGitHubClient
 
 monitoring_module = importlib.import_module('ddev.cli.release.test_agent.monitoring')
@@ -253,6 +257,38 @@ async def test_monitor_workflows_does_not_raise_on_job_failure(fake_async_github
     )
 
 
+async def test_monitor_workflows_does_not_swallow_authentication_errors(
+    fake_async_github: FakeAsyncGitHubClient,
+) -> None:
+    terminal = Terminal(verbosity=0, enable_color=False, interactive=False)
+    request = httpx.Request('GET', 'https://api.github.com/repos/DataDog/integrations-core/actions/runs/123')
+    error = httpx.HTTPStatusError('forbidden', request=request, response=httpx.Response(403))
+    fake_async_github.mock_response(
+        'get_workflow_run',
+        GitHubAuthenticationError.from_http_status_error(error),
+    )
+
+    async def unexpected_sleep(_: float) -> None:
+        raise AssertionError('authentication error was swallowed')
+
+    with pytest.raises(GitHubAuthenticationError):
+        await monitor_workflows(
+            terminal,
+            fake_async_github,
+            ref='7.80.x',
+            workflows=[
+                DispatchedWorkflow(
+                    label='Linux',
+                    workflow_id='test-agent.yml',
+                    run_id=123,
+                    html_url='https://github.com/DataDog/integrations-core/actions/runs/123',
+                )
+            ],
+            poll_interval=0,
+            sleep=unexpected_sleep,
+        )
+
+
 async def test_monitor_workflows_does_not_use_alternate_screen(
     fake_async_github: FakeAsyncGitHubClient, monkeypatch
 ) -> None:

ddev/tests/cli/release/test_port_commit.py

@@ -6,6 +6,7 @@
 from pathlib import Path as StdPath
 from unittest.mock import MagicMock, call
 
+import httpx
 import pytest
 from pytest_mock import MockerFixture
 
@@ -24,6 +25,7 @@
 )
 from ddev.utils.git import GitCommit
 from ddev.utils.github_async.models import PullRequest
+from ddev.utils.github_errors import GitHubAuthenticationError
 from tests.helpers.github_async import FakeAsyncGitHubClient
 from tests.helpers.runner import CliRunner
 
@@ -846,6 +848,27 @@ def test_command_aborts_when_pr_input_has_no_token(
     fake_async_github.assert_not_called('get_pull_request')
 
 
+def test_command_reports_actionable_github_authentication_error(
+    ddev: CliRunner, mocker: MockerFixture, fake_async_github: FakeAsyncGitHubClient
+) -> None:
+    error = httpx.HTTPStatusError(
+        'forbidden',
+        request=httpx.Request('GET', 'https://api.github.com/repos/DataDog/integrations-core/pulls/23703'),
+        response=httpx.Response(403),
+    )
+    fake_async_github.mock_response(
+        'get_pull_request',
+        GitHubAuthenticationError.from_http_status_error(error),
+    )
+    mocker.patch.dict('os.environ', {'DD_GITHUB_USER': 'alice'})
+
+    result = ddev('release', 'port-commit', '--dry-run', 'PR-23703')
+
+    assert result.exit_code == 1, result.output
+    assert 'GitHub denied the requested operation (HTTP 403)' in result.output
+    assert 'ddev config set github.token' in result.output
+
+
 def test_command_falls_back_to_commit_on_pr_not_found(
     ddev: CliRunner, mocker: MockerFixture, fake_async_github: FakeAsyncGitHubClient
 ) -> None: