fix: ignore GitHub API rate limit failures in update and health commands (#23032)

Author: Copilot

pkg/cli/health_command.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/github/gh-aw/pkg/console"
 	"github.com/github/gh-aw/pkg/constants"
+	"github.com/github/gh-aw/pkg/gitutil"
 	"github.com/github/gh-aw/pkg/logger"
 	"github.com/github/gh-aw/pkg/workflow"
 	"github.com/spf13/cobra"
@@ -135,6 +136,16 @@ func RunHealth(config HealthConfig) error {
 	// Fetch workflow runs from GitHub
 	runs, err := fetchWorkflowRuns(workflowAPIName, startDate, config.RepoOverride, config.Verbose)
 	if err != nil {
+		if gitutil.IsRateLimitError(err.Error()) {
+			// Rate limiting is a transient infrastructure condition, not a code error.
+			// Warn and exit cleanly so CI jobs are not marked as failed.
+			fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Skipping health check: GitHub API rate limit exceeded"))
+			if config.JSONOutput && config.WorkflowName != "" {
+				// Emit an empty-run JSON structure so callers can still parse the output.
+				return displayDetailedHealth(nil, config)
+			}
+			return nil
+		}
 		return fmt.Errorf("failed to fetch workflow runs: %w", err)
 	}
 

pkg/cli/update_workflows.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/github/gh-aw/pkg/console"
+	"github.com/github/gh-aw/pkg/gitutil"
 	"github.com/github/gh-aw/pkg/parser"
 	"github.com/github/gh-aw/pkg/workflow"
 )
@@ -64,12 +65,30 @@ func UpdateWorkflows(workflowNames []string, allowMajor, force, verbose bool, en
 	showUpdateSummary(successfulUpdates, failedUpdates)
 
 	if len(successfulUpdates) == 0 {
+		// If all failures were due to GitHub API rate limiting, treat as non-fatal.
+		// Rate limiting is a transient infrastructure condition, not a code error.
+		if len(failedUpdates) > 0 && allFailuresAreRateLimited(failedUpdates) {
+			fmt.Fprintln(os.Stderr, console.FormatWarningMessage("All workflow updates skipped due to GitHub API rate limiting"))
+			return nil
+		}
 		return errors.New("no workflows were successfully updated")
 	}
 
 	return nil
 }
 
+// allFailuresAreRateLimited returns true if every failed workflow update was caused
+// by a GitHub API rate limit error. Used to distinguish transient rate-limiting
+// (non-fatal) from genuine update failures (fatal).
+func allFailuresAreRateLimited(failures []updateFailure) bool {
+	for _, f := range failures {
+		if !gitutil.IsRateLimitError(f.Error) {
+			return false
+		}
+	}
+	return true
+}
+
 // findWorkflowsWithSource finds all workflows that have a source field
 func findWorkflowsWithSource(workflowsDir string, filterNames []string, verbose bool) ([]*workflowWithSource, error) {
 	updateLog.Printf("Finding workflows with source field in %s", workflowsDir)

pkg/gitutil/gitutil.go

@@ -10,6 +10,16 @@ import (
 
 var log = logger.New("gitutil:gitutil")
 
+// IsRateLimitError checks if an error message indicates a GitHub API rate limit error.
+// This is used to detect transient failures caused by hitting the GitHub API rate limit
+// (HTTP 403 "API rate limit exceeded" or HTTP 429 responses).
+func IsRateLimitError(errMsg string) bool {
+	lowerMsg := strings.ToLower(errMsg)
+	return strings.Contains(lowerMsg, "api rate limit exceeded") ||
+		strings.Contains(lowerMsg, "rate limit exceeded") ||
+		strings.Contains(lowerMsg, "secondary rate limit")
+}
+
 // IsAuthError checks if an error message indicates an authentication issue.
 // This is used to detect when GitHub API calls fail due to missing or invalid credentials.
 func IsAuthError(errMsg string) bool {

pkg/gitutil/gitutil_test.go

@@ -0,0 +1,111 @@
+//go:build !integration
+
+package gitutil
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsRateLimitError(t *testing.T) {
+	tests := []struct {
+		name     string
+		errMsg   string
+		expected bool
+	}{
+		{
+			name:     "GitHub API rate limit exceeded (HTTP 403)",
+			errMsg:   "gh: API rate limit exceeded for installation. If you reach out to GitHub Support for help, please include the request ID (HTTP 403)",
+			expected: true,
+		},
+		{
+			name:     "rate limit exceeded lowercase",
+			errMsg:   "rate limit exceeded",
+			expected: true,
+		},
+		{
+			name:     "HTTP 403 with API rate limit message",
+			errMsg:   "HTTP 403: API rate limit exceeded for installation.",
+			expected: true,
+		},
+		{
+			name:     "secondary rate limit in GitHub error message",
+			errMsg:   "gh: You have exceeded a secondary rate limit",
+			expected: true,
+		},
+		{
+			name:     "authentication error is not a rate limit error",
+			errMsg:   "authentication required. Run 'gh auth login' first",
+			expected: false,
+		},
+		{
+			name:     "not found error is not a rate limit error",
+			errMsg:   "HTTP 404: Not Found",
+			expected: false,
+		},
+		{
+			name:     "empty string",
+			errMsg:   "",
+			expected: false,
+		},
+		{
+			name:     "unrelated error message",
+			errMsg:   "failed to parse workflow runs: unexpected end of JSON input",
+			expected: false,
+		},
+		{
+			name:     "mixed case",
+			errMsg:   "API Rate Limit Exceeded for installation",
+			expected: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := IsRateLimitError(tt.errMsg)
+			assert.Equal(t, tt.expected, result, "IsRateLimitError(%q) should return %v", tt.errMsg, tt.expected)
+		})
+	}
+}
+
+func TestIsAuthError(t *testing.T) {
+	tests := []struct {
+		name     string
+		errMsg   string
+		expected bool
+	}{
+		{
+			name:     "GH_TOKEN mention",
+			errMsg:   "GH_TOKEN is not set",
+			expected: true,
+		},
+		{
+			name:     "authentication error",
+			errMsg:   "authentication required",
+			expected: true,
+		},
+		{
+			name:     "not logged in",
+			errMsg:   "not logged into any GitHub hosts",
+			expected: true,
+		},
+		{
+			name:     "rate limit error is not an auth error",
+			errMsg:   "API rate limit exceeded for installation",
+			expected: false,
+		},
+		{
+			name:     "empty string",
+			errMsg:   "",
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := IsAuthError(tt.errMsg)
+			assert.Equal(t, tt.expected, result, "IsAuthError(%q) should return %v", tt.errMsg, tt.expected)
+		})
+	}
+}