fix(governance): require explicit ruleset bypass mode

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/github/__toolsnaps__/create_repository_ruleset.snap

@@ -42,7 +42,8 @@
             }
           },
           "required": [
-            "actor_type"
+            "actor_type",
+            "bypass_mode"
           ],
           "type": "object"
         },

pkg/github/rulesets.go

@@ -798,7 +798,7 @@ func rulesetWriteProperties() map[string]*jsonschema.Schema {
 						Description: "When the specified actor can bypass the ruleset. 'pull_request' only applies to branch rulesets and is not valid for the 'DeployKey' actor type. 'exempt' means rules are not run for that actor and no bypass audit entry is created.",
 					},
 				},
-				Required: []string{"actor_type"},
+				Required: []string{"actor_type", "bypass_mode"},
 			},
 		},
 	}
@@ -888,6 +888,15 @@ func buildRepositoryRulesetFromArgs(args map[string]any) (github.RepositoryRules
 					return github.RepositoryRuleset{}, utils.NewToolResultError(fmt.Sprintf("bypass_actors[%d]: unsupported or unrecognized key: %q", i, key))
 				}
 			}
+			bypassMode, ok := actorMap["bypass_mode"].(string)
+			if !ok {
+				return github.RepositoryRuleset{}, utils.NewToolResultError(fmt.Sprintf("bypass_actors[%d].bypass_mode is required and must be a string", i))
+			}
+			switch github.BypassMode(bypassMode) {
+			case github.BypassModeAlways, github.BypassModePullRequest, github.BypassModeExempt:
+			default:
+				return github.RepositoryRuleset{}, utils.NewToolResultError(fmt.Sprintf("bypass_actors[%d].bypass_mode must be one of \"always\", \"pull_request\", or \"exempt\"", i))
+			}
 		}
 		payload["bypass_actors"] = bypassActorsArr
 	}

pkg/github/rulesets_test.go

@@ -564,6 +564,11 @@ func Test_CreateRepositoryRuleset(t *testing.T) {
 
 	resolvedSchema, err := schema.Resolve(nil)
 	require.NoError(t, err)
+	bypassActorSchema := schema.Properties["bypass_actors"].Items
+	require.NotNil(t, bypassActorSchema)
+	assert.ElementsMatch(t, []string{"actor_type", "bypass_mode"}, bypassActorSchema.Required)
+	assert.ElementsMatch(t, []any{"always", "pull_request", "exempt"}, bypassActorSchema.Properties["bypass_mode"].Enum)
+
 	validArgs := map[string]any{
 		"level":       "repository",
 		"owner":       "owner",
@@ -581,6 +586,15 @@ func Test_CreateRepositoryRuleset(t *testing.T) {
 	}
 	require.NoError(t, resolvedSchema.Validate(validArgs))
 
+	t.Run("bypass actor requires an explicit documented mode", func(t *testing.T) {
+		args := maps.Clone(validArgs)
+		args["bypass_actors"] = []any{map[string]any{"actor_type": "OrganizationAdmin"}}
+		require.Error(t, resolvedSchema.Validate(args))
+
+		args["bypass_actors"] = []any{map[string]any{"actor_type": "OrganizationAdmin", "bypass_mode": "never"}}
+		require.Error(t, resolvedSchema.Validate(args))
+	})
+
 	for _, test := range []struct {
 		field string
 		typo  string
@@ -944,6 +958,74 @@ func Test_CreateRepositoryRuleset(t *testing.T) {
 		assert.NotEmpty(t, capturedBody)
 	})
 
+	for _, bypassMode := range []string{"always", "pull_request", "exempt"} {
+		t.Run("bypass_actors serializes "+bypassMode+" exactly", func(t *testing.T) {
+			var capturedRaw []byte
+			client := mustNewGHClient(t, MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
+				"POST /repos/{owner}/{repo}/rulesets": func(w http.ResponseWriter, r *http.Request) {
+					capturedRaw, _ = io.ReadAll(r.Body)
+					w.WriteHeader(http.StatusCreated)
+					_, _ = w.Write(capturedRaw)
+				},
+			}))
+			deps := BaseDeps{Client: client}
+			handler := toolDef.Handler(deps)
+			request := createMCPRequest(map[string]any{
+				"level":       "repository",
+				"owner":       "owner",
+				"repo":        "repo",
+				"name":        "main protection",
+				"enforcement": "active",
+				"rules":       []any{map[string]any{"type": "creation"}},
+				"bypass_actors": []any{
+					map[string]any{"actor_type": "OrganizationAdmin", "bypass_mode": bypassMode},
+				},
+			})
+
+			result, err := handler(ContextWithDeps(context.Background(), deps), &request)
+			require.NoError(t, err)
+			require.False(t, result.IsError)
+
+			var outbound struct {
+				BypassActors []struct {
+					BypassMode string `json:"bypass_mode"`
+				} `json:"bypass_actors"`
+			}
+			require.NoError(t, json.Unmarshal(capturedRaw, &outbound))
+			require.Len(t, outbound.BypassActors, 1)
+			assert.Equal(t, bypassMode, outbound.BypassActors[0].BypassMode)
+		})
+	}
+
+	t.Run("bypass_actors without bypass_mode is rejected before request", func(t *testing.T) {
+		called := false
+		client := mustNewGHClient(t, MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
+			"POST /repos/{owner}/{repo}/rulesets": func(w http.ResponseWriter, _ *http.Request) {
+				called = true
+				w.WriteHeader(http.StatusCreated)
+			},
+		}))
+		deps := BaseDeps{Client: client}
+		handler := toolDef.Handler(deps)
+		request := createMCPRequest(map[string]any{
+			"level":       "repository",
+			"owner":       "owner",
+			"repo":        "repo",
+			"name":        "main protection",
+			"enforcement": "active",
+			"rules":       []any{map[string]any{"type": "creation"}},
+			"bypass_actors": []any{
+				map[string]any{"actor_type": "OrganizationAdmin"},
+			},
+		})
+
+		result, err := handler(ContextWithDeps(context.Background(), deps), &request)
+		require.NoError(t, err)
+		require.True(t, result.IsError)
+		assert.Contains(t, getErrorResult(t, result).Text, "bypass_actors[0].bypass_mode")
+		assert.False(t, called)
+	})
+
 	t.Run("bypass_actors accepts exempt bypass mode and enterprise actor types", func(t *testing.T) {
 		var capturedBody github.RepositoryRuleset
 		client := mustNewGHClient(t, MockHTTPClientWithHandlers(map[string]http.HandlerFunc{