@@ -0,0 +1,102 @@
+package main
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/github/gh-actions-lock/internal/ghapi/httpmock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestRun_ParitySSOGuidance(t *testing.T) {
+	const message = "Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization."
+	for _, mode := range []struct {
+		name string
+		args []string
+	}{
+		{"fix", nil},
+		{"no-fix", []string{"--no-fix"}},
+		{"verify", []string{"--verify"}},
+	} {
+		t.Run(mode.name, func(t *testing.T) {
+			t.Setenv("CODESPACES", "")
+			reg := &httpmock.Registry{}
+			reg.Register(httpmock.GraphQL(`commit: object\(oid`), func(req *http.Request) (*http.Response, error) {
+				resp, err := httpmock.JSONResponse(map[string]string{"message": message})(req)
+				if err != nil {
+					return nil, err
+				}
+				resp.StatusCode = http.StatusForbidden
+				return resp, nil
+			})
+			reg.Register(httpmock.REST("GET", `^/repos/krzema12/github-actions-typing$`), httpmock.StatusResponse(http.StatusNotFound))
+			path := writeTempWorkflow(t, transferWorkflow, "krzema12/github-actions-typing@v2.2.2=sha1-"+parityTestSHA)
+			lockBefore := readTempLockfilePins(t)
+
+			_, stderr, err := runCommandWithHTTP(t, reg, append(mode.args, "--no-interactive", path)...)
+			require.ErrorIs(t, err, errSilent)
+			assert.Contains(t, stderr, "GitHub returned 403 Forbidden: "+message)
+			assert.NotContains(t, stderr, "https://api.github.com/")
+			assert.Equal(t, 1, strings.Count(stderr, message))
+			if mode.name != "fix" {
+				assert.Equal(t, 1, strings.Count(stderr, "gh auth refresh -h github.com"))
+			}
+			assert.Equal(t, lockBefore, readTempLockfilePins(t))
+			reg.Verify(t)
+		})
+	}
+}
+
+func TestRun_ParitySSORateLimitedGuidance(t *testing.T) {
+	const message = "Resource protected by organization SAML enforcement."
+	for _, mode := range []struct {
+		name string
+		args []string
+	}{
+		{"fix", nil},
+		{"no-fix", []string{"--no-fix"}},
+		{"verify", []string{"--verify"}},
+	} {
+		t.Run(mode.name, func(t *testing.T) {
+			t.Setenv("CODESPACES", "true")
+			reg := &httpmock.Registry{}
+			reg.Register(httpmock.GraphQL(`commit: object\(oid`), httpmock.JSONResponse(map[string]any{
+				"data": map[string]any{"a0": map[string]any{
+					"nameWithOwner": "krzema12/github-actions-typing",
+					"databaseId":    1,
+					"commit":        map[string]any{"oid": parityTestSHA},
+					"tag":           map[string]any{"oid": parityTestMoved},
+					"tagRef":        map[string]any{"oid": parityTestMoved},
+				}},
+			}))
+			reg.RegisterReusable(httpmock.REST("HEAD", `^/orgs/krzema12$`), httpmock.StatusResponse(http.StatusOK))
+			reg.Register(httpmock.REST("GET", `^/repos/krzema12/github-actions-typing/compare/`), func(req *http.Request) (*http.Response, error) {
+				resp, err := httpmock.JSONResponse(map[string]string{"message": message})(req)
+				if err != nil {
+					return nil, err
+				}
+				resp.StatusCode = http.StatusForbidden
+				return resp, nil
+			})
+			reg.Register(httpmock.REST("GET", `^/repos/krzema12/github-actions-typing/compare/`), httpmock.StatusResponse(http.StatusTooManyRequests))
+			useDefaultTransport(t, reg)
+			path := writeTempWorkflow(t, transferWorkflow, "krzema12/github-actions-typing@v2.2.2=sha1-"+parityTestSHA)
+			lockBefore := readTempLockfilePins(t)
+
+			_, stderr, err := runCommandWithHTTP(t, reg, append(mode.args, "--no-interactive", path)...)
+			require.ErrorIs(t, err, errSilent)
+			assert.Contains(t, stderr, "SSO authorization required")
+			assert.Contains(t, stderr, "Authorize it at https://github.com/orgs/krzema12/sso and retry")
+			assert.Contains(t, stderr, "anonymous fallback for public repositories was rate-limited")
+			assert.NotContains(t, stderr, "https://api.github.com/")
+			assert.Equal(t, 1, strings.Count(stderr, "Authorize it at"))
+			if mode.name != "fix" {
+				assert.Equal(t, 1, strings.Count(stderr, "Your codespace's GITHUB_TOKEN cannot be SSO-authorized."))
+			}
+			assert.Equal(t, lockBefore, readTempLockfilePins(t))
+			reg.Verify(t)
+		})
+	}
+}
@@ -1,15 +1,27 @@
 package ghapi
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
+
+	"github.com/cli/go-gh/v2/pkg/api"
 )
 
-// Brief formats err for one terminal line: an HTTP failure as its status
-// alone, without the request URL. The run log and --json keep the full error.
+// Brief omits HTTP request URLs and keeps authorization guidance, shortening
+// other HTTP failures to their status. The run log and --json keep the full error.
 func Brief(err error) string {
+	var ssoErr *SSORateLimitedError
+	if errors.As(err, &ssoErr) {
+		return ssoErr.Error()
+	}
 	if code, ok := StatusCode(err); ok {
-		return fmt.Sprintf("GitHub returned %d %s", code, http.StatusText(code))
+		msg := fmt.Sprintf("GitHub returned %d %s", code, http.StatusText(code))
+		var httpErr *api.HTTPError
+		if IsSAMLEnforcement(err) && errors.As(err, &httpErr) {
+			msg += ": " + httpErr.Message
+		}
+		return msg
 	}
 	return err.Error()
 }
 
@@ -0,0 +1,75 @@
+package ghapi
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"testing"
+
+	"github.com/cli/go-gh/v2/pkg/api"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestBrief(t *testing.T) {
+	requestURL, err := url.Parse("https://api.github.com/repos/acme/widget/commits/v1")
+	assert.NoError(t, err)
+	const saml = "Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization."
+	for _, tt := range []struct {
+		name string
+		err  error
+		want string
+	}{
+		{
+			name: "ordinary HTTP failure omits message and request URL",
+			err:  &api.HTTPError{StatusCode: http.StatusServiceUnavailable, RequestURL: requestURL, Message: "upstream unavailable"},
+			want: "GitHub returned 503 Service Unavailable",
+		},
+		{
+			name: "ordinary forbidden failure remains concise",
+			err:  &api.HTTPError{StatusCode: http.StatusForbidden, RequestURL: requestURL, Message: "Resource not accessible by integration"},
+			want: "GitHub returned 403 Forbidden",
+		},
+		{
+			name: "wrapped SAML failure retains authorization instructions",
+			err:  fmt.Errorf("fetching commit: %w", &api.HTTPError{StatusCode: http.StatusForbidden, RequestURL: requestURL, Message: saml}),
+			want: "GitHub returned 403 Forbidden: " + saml,
+		},
+		{
+			name: "SAML SSO failure retains authorization instructions",
+			err:  &api.HTTPError{StatusCode: http.StatusForbidden, RequestURL: requestURL, Message: "SAML SSO required. Authorize your token and retry."},
+			want: "GitHub returned 403 Forbidden: SAML SSO required. Authorize your token and retry.",
+		},
+		{
+			name: "wrapped rate-limited SSO fallback retains authorization URL",
+			err: fmt.Errorf("fetching commit: %w", &SSORateLimitedError{
+				Host: "github.com", Owner: "acme",
+				Err: &api.HTTPError{StatusCode: http.StatusTooManyRequests, RequestURL: requestURL},
+			}),
+			want: ssoRequiredMessage("github.com", "acme") + " (the anonymous fallback for public repositories was rate-limited)",
+		},
+		{
+			name: "GraphQL SSO guidance is unchanged",
+			err:  errors.New(ssoRequiredMessage("github.com", "acme")),
+			want: ssoRequiredMessage("github.com", "acme"),
+		},
+		{
+			name: "non-HTTP error is unchanged",
+			err:  errors.New("connection refused"),
+			want: "connection refused",
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			wrapped := &BriefError{Msg: Brief(tt.err), Err: tt.err}
+			assert.Equal(t, tt.want, wrapped.Error())
+			assert.NotContains(t, wrapped.Error(), requestURL.String())
+			assert.ErrorIs(t, wrapped, tt.err)
+			assert.Equal(t, tt.err.Error(), wrapped.Verbose())
+			if code, ok := StatusCode(tt.err); ok {
+				got, found := StatusCode(wrapped)
+				assert.True(t, found)
+				assert.Equal(t, code, got)
+			}
+		})
+	}
+}