fix: a forbidden service fails alone and its error says where to look

Author: lesnik512

README.md

@@ -24,7 +24,10 @@ uvx release-scope collect --group team/backend --output report.json --cache cach
 ```
 
 `--group` and `--project` are repeatable and can be mixed. The command exits `1` when any service failed to
-collect; the report is still written and names the error on that service.
+collect; the report is still written and names the error on that service. A service GitLab denies access to fails
+alone, and its error lists the project settings and member page to check. A project with CI/CD or Environments
+disabled is reported with a warning and no rows, without querying it. Only a rejected token, or a group or project
+passed on the command line that the token cannot see, stops the run.
 
 ## Configuration
 

release_scope/__main__.py

@@ -91,7 +91,7 @@ def _collect_command(  # noqa: PLR0913, PLR0917
     rows: typing.Final = sum(len(service.rows) for service in report.services)
     typer.echo(f"{len(report.services)} services, {rows} rows, {len(failed)} failed -> {output}", err=True)
     for service in failed:
-        typer.echo(f"Error: {service.project}: {service.error}", err=True)
+        typer.echo(f"Error: {service.error}", err=True)
     if failed:
         raise typer.Exit(code=1)
 

release_scope/_errors.py

@@ -15,3 +15,9 @@ class AuthError(ReleaseScopeError):
 
 class GitLabError(ReleaseScopeError):
     exit_code: typing.ClassVar[int] = 4
+
+    def __init__(self, message: str, *, path: str, status: int | None = None, reason: str = "") -> None:
+        super().__init__(message)
+        self.path = path
+        self.status = status
+        self.reason = reason

release_scope/_gitlab.py

@@ -2,7 +2,7 @@
 import datetime
 import math
 import typing
-from urllib.parse import quote
+from urllib.parse import quote, unquote
 
 import httpware
 import pydantic
@@ -22,6 +22,8 @@ class Project(pydantic.BaseModel):
     path_with_namespace: str
     web_url: str
     default_branch: str | None = None
+    builds_access_level: str | None = None
+    environments_access_level: str | None = None
 
 
 class Deployable(pydantic.BaseModel):
@@ -134,13 +136,13 @@ class _Bridges(pydantic.RootModel[list[Bridge]]):
 
 
 def _translate(exc: httpware.ClientError, *, url: str) -> Exception:
-    if isinstance(exc, (httpware.UnauthorizedError, httpware.ForbiddenError)):
-        return AuthError(
-            f"GitLab rejected the token ({exc.response.status_code}) for {url}. It needs 'read_api' scope."
-        )
+    if isinstance(exc, httpware.UnauthorizedError):
+        return AuthError("GitLab rejected the token (401). Check that it is valid and not expired.")
     if isinstance(exc, httpware.StatusError):
-        return GitLabError(f"GitLab returned {exc.response.status_code} for {url}.")
-    return GitLabError(f"GitLab request {url} failed: {type(exc).__name__}.")
+        status: typing.Final = exc.response.status_code
+        return GitLabError(f"GitLab returned {status} for {unquote(url)}.", path=url, status=status)
+    reason: typing.Final = type(exc).__name__
+    return GitLabError(f"GitLab request {unquote(url)} failed: {reason}.", path=url, reason=reason)
 
 
 def _quote(value: str) -> str:

release_scope/_messages.py

@@ -0,0 +1,54 @@
+import re
+import typing
+
+from release_scope._errors import GitLabError
+from release_scope._gitlab import Project
+
+
+_FORBIDDEN: typing.Final = 403
+_PROJECT_RESOURCE: typing.Final = re.compile(r"/projects/[^/]+/([^/?]+)")
+_RESOURCES: typing.Final[dict[str, tuple[str, tuple[str, ...]]]] = {
+    "deployments": ("deployments", ("Environments", "CI/CD")),
+    "pipelines": ("pipelines", ("CI/CD",)),
+    "repository": ("the repository", ("Repository",)),
+    "merge_requests": ("merge requests", ("Merge requests",)),
+}
+_PLURAL_FEATURES: typing.Final = frozenset({"Environments", "Merge requests"})
+
+
+def _feature_setting(project: Project, feature: str) -> str:
+    return f"{project.web_url}/edit#js-shared-permissions → Visibility, project features, permissions → {feature}"
+
+
+def _resource(path: str) -> tuple[str, tuple[str, ...]]:
+    match: typing.Final = _PROJECT_RESOURCE.search(path)
+    return _RESOURCES.get(match.group(1), ("project data", ())) if match else ("project data", ())
+
+
+def explain_failure(project: Project, error: GitLabError) -> str:
+    name: typing.Final = project.path_with_namespace
+    resource, features = _resource(error.path)
+    if error.status is None:
+        return f"{name}: GitLab request for {resource} failed ({error.reason})."
+    if error.status != _FORBIDDEN:
+        return f"{name}: GitLab returned {error.status} for {resource}."
+    checks: typing.Final = [
+        f"- {feature} {'are' if feature in _PLURAL_FEATURES else 'is'} enabled: {_feature_setting(project, feature)}"
+        for feature in features
+    ]
+    checks.append(f"- the token's user has a role that can read them: {project.web_url}/-/project_members")
+    return "\n".join([f"{name}: GitLab denied access to {resource} (403). Check that:", *checks])
+
+
+def skip_reason(project: Project) -> str | None:
+    if project.builds_access_level == "disabled":
+        return (
+            "CI/CD is disabled, so it has no pipelines or deployments. "
+            f"Enable it at {_feature_setting(project, 'CI/CD')}."
+        )
+    if project.environments_access_level == "disabled":
+        return (
+            "Environments are disabled, so it has no deployments. "
+            f"Enable them at {_feature_setting(project, 'Environments')}."
+        )
+    return None

release_scope/_use_case.py

@@ -5,9 +5,10 @@
 from urllib.parse import quote
 
 from release_scope._cache import Cache, CachedPipeline
-from release_scope._errors import GitLabError
+from release_scope._errors import AuthError, GitLabError
 from release_scope._gitlab import Commit, Deployment, GitLabApi, MergeRequest, Pipeline, Project
 from release_scope._jira_keys import extract_jira_keys
+from release_scope._messages import explain_failure, skip_reason
 from release_scope._report import (
     CommitRef,
     EnvironmentState,
@@ -24,9 +25,19 @@
 from release_scope._settings import Settings
 
 
+_FORBIDDEN: typing.Final = 403
 _SETTLED_PIPELINE_STATUSES: typing.Final = frozenset({"success", "failed", "canceled", "skipped"})
 
 
+def _resolution_error(error: GitLabError, target: str) -> Exception:
+    if error.status == _FORBIDDEN:
+        return AuthError(
+            f"GitLab denied access to {target} (403). "
+            "Check that the token has the 'read_api' scope and that its user can see it."
+        )
+    return error
+
+
 def _environment_state(name: str, deployment: Deployment) -> EnvironmentState:
     return EnvironmentState(
         name=name,
@@ -79,7 +90,11 @@ def __call__(
             except GitLabError as exc:
                 cache.keep_project(project.id)
                 services.append(
-                    Service(project=project.path_with_namespace, project_url=project.web_url, error=str(exc))
+                    Service(
+                        project=project.path_with_namespace,
+                        project_url=project.web_url,
+                        error=explain_failure(project, exc),
+                    )
                 )
         return Report(
             collected_at=datetime.datetime.now(datetime.UTC),
@@ -96,17 +111,27 @@ def _resolve_projects(
     ) -> list[Project]:
         resolved: dict[int, Project] = {}
         for group in groups:
-            for project in self.api.list_group_projects(group, include_subgroups=include_subgroups):
-                resolved[project.id] = project
+            try:
+                listed = self.api.list_group_projects(group, include_subgroups=include_subgroups)
+            except GitLabError as exc:
+                raise _resolution_error(exc, f"group '{group}'") from exc
+            resolved.update((project.id, project) for project in listed)
         for path in projects:
-            project = self.api.get_project(path)
+            try:
+                project = self.api.get_project(path)
+            except GitLabError as exc:
+                raise _resolution_error(exc, f"project '{path}'") from exc
             resolved[project.id] = project
         return sorted(resolved.values(), key=lambda item: item.path_with_namespace)
 
     def _collect_service(self, project: Project, cache: Cache) -> Service:
         service: typing.Final = Service(
             project=project.path_with_namespace, project_url=project.web_url, default_branch=project.default_branch
         )
+        reason: typing.Final = skip_reason(project)
+        if reason is not None:
+            service.warnings.append(reason)
+            return service
         for name in self.settings.environments:
             deployment = self.api.latest_deployment(project.id, name)
             if deployment is not None:

tests/payloads.py

@@ -6,12 +6,19 @@
 SERVICE_API: typing.Final = f"{API}/projects/1"
 
 
-def project(project_id: int, path: str, *, default_branch: str | None = "main") -> dict[str, typing.Any]:
+def project(
+    project_id: int,
+    path: str,
+    *,
+    default_branch: str | None = "main",
+    **fields: typing.Any,  # noqa: ANN401
+) -> dict[str, typing.Any]:
     return {
         "id": project_id,
         "path_with_namespace": path,
         "web_url": f"{ENDPOINT}/{path}",
         "default_branch": default_branch,
+        **fields,
     }
 
 

tests/test_cli.py

@@ -77,7 +77,7 @@ def test_failed_service_is_reported_and_exits_non_zero(gitlab: respx.Router, tmp
     result: typing.Final = _invoke("collect", "-g", "team", "-o", str(output))
 
     assert result.exit_code == 1
-    assert "Error: team/broken: GitLab returned 400" in result.output
+    assert "Error: team/broken: GitLab returned 400 for deployments." in result.output
     assert [item["error"] is None for item in json.loads(output.read_text())["services"]] == [False, True]
 
 
@@ -89,7 +89,7 @@ def test_authentication_failure_exits_with_auth_code(httpx2_mock: respx.Router,
     result: typing.Final = _invoke("collect", "-g", "team", "-o", str(output))
 
     assert result.exit_code == 3
-    assert "Error: GitLab rejected the token (403)" in result.output
+    assert "Error: GitLab denied access to group 'team' (403)" in result.output
     assert not output.exists()
 
 

tests/test_use_case.py

@@ -1,5 +1,6 @@
 import typing
 
+import httpcore2
 import httpware
 import httpx
 import pydantic
@@ -156,12 +157,105 @@ def test_a_failing_service_keeps_its_cache_and_does_not_stop_the_others(gitlab:
     report: typing.Final = _collect(next_cache)
 
     assert [(item.project, item.error) for item in report.services] == [
-        ("team/broken", "GitLab returned 500 for /api/v4/projects/2/deployments."),
-        ("team/svc", "GitLab returned 502 for /api/v4/projects/1/deployments."),
+        ("team/broken", "team/broken: GitLab returned 500 for deployments."),
+        ("team/svc", "team/svc: GitLab returned 502 for deployments."),
     ]
     assert next_cache.current.pipelines["1"] == cache.current.pipelines["1"]
 
 
+def test_forbidden_deployments_fail_only_that_service_and_say_where_to_look(gitlab: respx.Router) -> None:
+    gitlab["group"].respond(json=[SERVICE, project(2, "team/nodeploy")])
+    gitlab.get(f"{API}/projects/2/deployments").respond(403)
+    settings: typing.Final = f"{ENDPOINT}/team/nodeploy/edit#js-shared-permissions"
+
+    report: typing.Final = _collect()
+
+    assert [item.project for item in report.services] == ["team/nodeploy", "team/svc"]
+    assert report.services[0].error == (
+        "team/nodeploy: GitLab denied access to deployments (403). Check that:\n"
+        f"- Environments are enabled: {settings} → Visibility, project features, permissions → Environments\n"
+        f"- CI/CD is enabled: {settings} → Visibility, project features, permissions → CI/CD\n"
+        f"- the token's user has a role that can read them: {ENDPOINT}/team/nodeploy/-/project_members"
+    )
+    assert len(report.services[1].rows) == 5
+
+
+@pytest.mark.httpx2(assert_all_called=False)
+@pytest.mark.parametrize(
+    ("route", "resource", "feature", "enabled"),
+    [
+        ("commits", "the repository", "Repository", "Repository is enabled"),
+        ("merged_mrs", "merge requests", "Merge requests", "Merge requests are enabled"),
+        ("push_pipelines", "pipelines", "CI/CD", "CI/CD is enabled"),
+    ],
+)
+def test_forbidden_resource_lists_the_feature_that_guards_it(
+    gitlab: respx.Router, route: str, resource: str, feature: str, enabled: str
+) -> None:
+    gitlab[route].respond(403)
+    settings: typing.Final = f"{ENDPOINT}/team/svc/edit#js-shared-permissions"
+
+    error: typing.Final = _only_service(_collect()).error
+
+    assert error == (
+        f"team/svc: GitLab denied access to {resource} (403). Check that:\n"
+        f"- {enabled}: {settings} → Visibility, project features, permissions → {feature}\n"
+        f"- the token's user has a role that can read them: {ENDPOINT}/team/svc/-/project_members"
+    )
+
+
+@pytest.mark.httpx2(assert_all_called=False)
+def test_network_failure_names_the_project(gitlab: respx.Router) -> None:
+    gitlab["tags"].mock(side_effect=httpcore2.ConnectError("down"))
+
+    assert _only_service(_collect()).error == "team/svc: GitLab request for the repository failed (NetworkError)."
+
+
+_LIB_FEATURES: typing.Final = (
+    f"{ENDPOINT}/team/lib/edit#js-shared-permissions → Visibility, project features, permissions"
+)
+
+
+@pytest.mark.parametrize(
+    ("access_levels", "warning"),
+    [
+        (
+            {"environments_access_level": "disabled"},
+            f"Environments are disabled, so it has no deployments. Enable them at {_LIB_FEATURES} → Environments.",
+        ),
+        (
+            {"builds_access_level": "disabled"},
+            f"CI/CD is disabled, so it has no pipelines or deployments. Enable it at {_LIB_FEATURES} → CI/CD.",
+        ),
+    ],
+)
+def test_project_without_deployments_is_skipped_with_a_warning(
+    gitlab: respx.Router, access_levels: dict[str, str], warning: str
+) -> None:
+    gitlab["group"].respond(json=[SERVICE, project(2, "team/lib", **access_levels)])
+
+    report: typing.Final = _collect()
+
+    skipped: typing.Final = report.services[0]
+    assert (skipped.project, skipped.rows, skipped.error, skipped.warnings) == ("team/lib", [], None, [warning])
+    assert len(report.services[1].rows) == 5
+
+
+def test_enabled_or_private_features_are_collected(gitlab: respx.Router) -> None:
+    gitlab["group"].respond(
+        json=[project(1, "team/svc", environments_access_level="private", builds_access_level="enabled")]
+    )
+
+    assert len(_only_service(_collect()).rows) == 5
+
+
+def test_forbidden_group_stops_the_run(httpx2_mock: respx.Router) -> None:
+    httpx2_mock.get(f"{API}/groups/team/projects").respond(403)
+
+    with pytest.raises(AuthError, match=r"GitLab denied access to group 'team' \(403\)"):
+        _collect()
+
+
 def test_authentication_failure_stops_the_run(httpx2_mock: respx.Router) -> None:
     httpx2_mock.get(f"{API}/groups/team/projects").respond(401)