Allow on.roles single-string role values (not just all) (#26789)

Author: Copilot

docs/src/content/docs/reference/frontmatter.md

@@ -237,6 +237,8 @@ on:
   roles: all                         # Allow any user (⚠️ use with caution)
 ```
 
+You can also use a single role string, for example `roles: write`.
+
 Available roles: `admin`, `maintainer`/`maintain`, `write`, `triage`, `read`, `all`. Workflows with unsafe triggers (`push`, `issues`, `pull_request`) automatically enforce permission checks. Failed checks cancel the workflow with a warning.
 
 > [!TIP]

pkg/parser/schemas/main_workflow_schema.json

@@ -1840,8 +1840,8 @@
               "oneOf": [
                 {
                   "type": "string",
-                  "enum": ["all"],
-                  "description": "Allow any authenticated user to trigger the workflow (\u26a0\ufe0f disables permission checking entirely - use with caution)"
+                  "enum": ["admin", "maintainer", "maintain", "write", "triage", "read", "all"],
+                  "description": "Single repository permission level that can trigger the workflow. Use 'all' to allow any authenticated user (\u26a0\ufe0f disables permission checking entirely - use with caution)"
                 },
                 {
                   "type": "array",

pkg/workflow/role_checks_test.go

@@ -148,6 +148,43 @@ Test that role membership check uses GITHUB_TOKEN with bots.`
 	}
 }
 
+func TestRoleMembershipSupportsSingleRoleString(t *testing.T) {
+	tmpDir := testutil.TempDir(t, "role-membership-single-role-string-test")
+
+	compiler := NewCompiler()
+
+	frontmatter := `---
+on:
+  pull_request:
+    types: [opened]
+  roles: write
+---
+
+# Test Workflow
+Test that on.roles supports a single string permission value.`
+
+	workflowPath := filepath.Join(tmpDir, "role-membership-single-role-string.md")
+	err := os.WriteFile(workflowPath, []byte(frontmatter), 0644)
+	if err != nil {
+		t.Fatalf("Failed to write workflow file: %v", err)
+	}
+
+	err = compiler.CompileWorkflow(workflowPath)
+	if err != nil {
+		t.Fatalf("Expected workflow with on.roles as a single string to compile successfully: %v", err)
+	}
+
+	outputPath := filepath.Join(tmpDir, "role-membership-single-role-string.lock.yml")
+	compiledContent, err := os.ReadFile(outputPath)
+	if err != nil {
+		t.Fatalf("Failed to read compiled workflow: %v", err)
+	}
+
+	compiledStr := string(compiledContent)
+	assert.Contains(t, compiledStr, "id: check_membership", "Compiled workflow should include membership checks for role-gated triggers")
+	assert.Contains(t, compiledStr, "write", "Compiled workflow should require the single role provided as a string")
+}
+
 func TestInferEventsFromTriggers(t *testing.T) {
 	c := &Compiler{}