improve dependabot error message

aashah · aashah · commit 031051bbda55 · 2026-04-23T11:24:50.000-07:00
diff --git a/pkg/github/dependabot.go b/pkg/github/dependabot.go
@@ -69,7 +69,7 @@ func GetDependabotAlert(t translations.TranslationHelperFunc) inventory.ServerTo
 			alert, resp, err := client.Dependabot.GetRepoAlert(ctx, owner, repo, alertNumber)
 			if err != nil {
 				return ghErrors.NewGitHubAPIErrorResponse(ctx,
-					fmt.Sprintf("failed to get alert with number '%d'", alertNumber),
+					dependabotErrMsg(fmt.Sprintf("failed to get alert with number '%d'", alertNumber), owner, repo, resp),
 					resp,
 					err,
 				), nil, nil
@@ -160,7 +160,7 @@ func ListDependabotAlerts(t translations.TranslationHelperFunc) inventory.Server
 			})
 			if err != nil {
 				return ghErrors.NewGitHubAPIErrorResponse(ctx,
-					fmt.Sprintf("failed to list alerts for repository '%s/%s'", owner, repo),
+					dependabotErrMsg(fmt.Sprintf("failed to list alerts for repository '%s/%s'", owner, repo), owner, repo, resp),
 					resp,
 					err,
 				), nil, nil
@@ -184,3 +184,16 @@ func ListDependabotAlerts(t translations.TranslationHelperFunc) inventory.Server
 		},
 	)
 }
+
+// dependabotErrMsg enhances error messages for dependabot API failures by
+// appending a hint about token permissions when the response indicates
+// the token may lack access to the repository (403 or 404).
+func dependabotErrMsg(base, owner, repo string, resp *github.Response) string {
+	if resp != nil && (resp.StatusCode == http.StatusForbidden || resp.StatusCode == http.StatusNotFound) {
+		return fmt.Sprintf("%s. Your token may not have access to Dependabot alerts on %s/%s. "+
+			"To access Dependabot alerts, the token needs the 'security_events' scope or, for fine-grained tokens, "+
+			"Dependabot alerts read permission for this specific repository.",
+			base, owner, repo)
+	}
+	return base
+}
diff --git a/pkg/github/dependabot_test.go b/pkg/github/dependabot_test.go
@@ -66,7 +66,23 @@ func Test_GetDependabotAlert(t *testing.T) {
 				"alertNumber": float64(9999),
 			},
 			expectError:    true,
-			expectedErrMsg: "failed to get alert",
+			expectedErrMsg: "Your token may not have access to Dependabot alerts on owner/repo",
+		},
+		{
+			name: "alert fetch forbidden",
+			mockedClient: MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
+				GetReposDependabotAlertsByOwnerByRepoByAlertNumber: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					w.WriteHeader(http.StatusForbidden)
+					_, _ = w.Write([]byte(`{"message": "Resource not accessible by integration"}`))
+				}),
+			}),
+			requestArgs: map[string]any{
+				"owner":       "owner",
+				"repo":        "repo",
+				"alertNumber": float64(42),
+			},
+			expectError:    true,
+			expectedErrMsg: "Your token may not have access to Dependabot alerts on owner/repo",
 		},
 	}
 
@@ -208,6 +224,21 @@ func Test_ListDependabotAlerts(t *testing.T) {
 			expectError:    true,
 			expectedErrMsg: "failed to list alerts",
 		},
+		{
+			name: "alerts listing forbidden includes token hint",
+			mockedClient: MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
+				GetReposDependabotAlertsByOwnerByRepo: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					w.WriteHeader(http.StatusForbidden)
+					_, _ = w.Write([]byte(`{"message": "Resource not accessible by integration"}`))
+				}),
+			}),
+			requestArgs: map[string]any{
+				"owner": "owner",
+				"repo":  "repo",
+			},
+			expectError:    true,
+			expectedErrMsg: "Your token may not have access to Dependabot alerts on owner/repo",
+		},
 	}
 
 	for _, tc := range tests {
