[WIP] Add missing organization-custom-org-roles and organization-custom-repository-roles to JSON Schema (#56982)

Author: Copilot

docs/public/editor/autocomplete-data.json

@@ -486,6 +486,18 @@
           "enum": ["read", "write", "none"],
           "leaf": true
         },
+        "organization-custom-org-roles": {
+          "type": "string",
+          "desc": "Permission level for organization custom org roles (read/write/none).",
+          "enum": ["read", "write", "none"],
+          "leaf": true
+        },
+        "organization-custom-repository-roles": {
+          "type": "string",
+          "desc": "Permission level for organization custom repository roles (read/write/none).",
+          "enum": ["read", "write", "none"],
+          "leaf": true
+        },
         "security-events": {
           "type": "string",
           "desc": "Permission level for security events (read/write/none).",

pkg/parser/schema_errors.go

@@ -312,8 +312,8 @@ func findFrontmatterBounds(lines []string) (startIdx int, endIdx int, frontmatte
 var knownFieldValidValues = map[string]string{
 	// Both entries mirror $defs/github_actions_permissions in main_workflow_schema.json.
 	// Update both when the schema changes.
-	"/permissions":    "Valid permission scopes: actions, all, attestations, checks, code-quality, copilot-requests, contents, deployments, discussions, id-token, issues, metadata, models, organization-projects, packages, pages, pull-requests, repository-projects, security-events, statuses, vulnerability-alerts",
-	"/on/permissions": "Valid permission scopes: actions, all, attestations, checks, code-quality, copilot-requests, contents, deployments, discussions, id-token, issues, metadata, models, organization-projects, packages, pages, pull-requests, repository-projects, security-events, statuses, vulnerability-alerts",
+	"/permissions":    "Valid permission scopes: actions, all, attestations, checks, code-quality, copilot-requests, contents, deployments, discussions, id-token, issues, metadata, models, organization-custom-org-roles, organization-custom-repository-roles, organization-projects, packages, pages, pull-requests, repository-projects, security-events, statuses, vulnerability-alerts",
+	"/on/permissions": "Valid permission scopes: actions, all, attestations, checks, code-quality, copilot-requests, contents, deployments, discussions, id-token, issues, metadata, models, organization-custom-org-roles, organization-custom-repository-roles, organization-projects, packages, pages, pull-requests, repository-projects, security-events, statuses, vulnerability-alerts",
 }
 
 // knownFieldScopes maps well-known JSON schema paths to a slice of valid scope names.
@@ -325,12 +325,14 @@ var knownFieldScopes = map[string][]string{
 	"/permissions": {
 		"actions", "all", "attestations", "checks", "code-quality", "copilot-requests", "contents", "deployments",
 		"discussions", "id-token", "issues", "metadata", "models",
+		"organization-custom-org-roles", "organization-custom-repository-roles",
 		"organization-projects", "packages", "pages", "pull-requests",
 		"repository-projects", "security-events", "statuses", "vulnerability-alerts",
 	},
 	"/on/permissions": {
 		"actions", "all", "attestations", "checks", "code-quality", "copilot-requests", "contents", "deployments",
 		"discussions", "id-token", "issues", "metadata", "models",
+		"organization-custom-org-roles", "organization-custom-repository-roles",
 		"organization-projects", "packages", "pages", "pull-requests",
 		"repository-projects", "security-events", "statuses", "vulnerability-alerts",
 	},

pkg/parser/schemas/main_workflow_schema.json

@@ -14964,6 +14964,16 @@
           "enum": ["read", "write", "none"],
           "description": "Permission level for organization projects (read/write/none). Controls access to manage organization-level GitHub Projects boards."
         },
+        "organization-custom-org-roles": {
+          "type": "string",
+          "enum": ["read", "write", "none"],
+          "description": "Permission level for organization custom org roles (read/write/none). Controls access to custom organization role metadata."
+        },
+        "organization-custom-repository-roles": {
+          "type": "string",
+          "enum": ["read", "write", "none"],
+          "description": "Permission level for organization custom repository roles (read/write/none). Controls access to custom repository role metadata."
+        },
         "security-events": {
           "type": "string",
           "enum": ["read", "write", "none"],

pkg/workflow/permissions_schema_consistency_test.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"testing"
 
+	"github.com/github/gh-aw/pkg/parser"
 	"github.com/stretchr/testify/require"
 )
 
@@ -62,6 +63,19 @@ func TestPermissionConstantsMatchSchemaEnum(t *testing.T) {
 		}
 	}
 
+	// Workflow-level permissions continue to accept custom org/repo role scopes,
+	// even though they are only available via GitHub App tokens when minting a
+	// token for the workflow.
+	for _, scope := range []PermissionScope{
+		PermissionOrganizationCustomOrgRoles,
+		PermissionOrganizationCustomRepositoryRoles,
+	} {
+		if _, ok := actionsPermProps[string(scope)]; !ok {
+			t.Errorf("permission scope %q from GetAllGitHubAppOnlyScopes() is missing from "+
+				"$defs.github_actions_permissions.properties in pkg/parser/schemas/main_workflow_schema.json", scope)
+		}
+	}
+
 	// GitHub App-only scopes must appear under either github_actions_permissions
 	// (e.g. organization-projects, which is grouped there for historical reasons) or
 	// github_app_permissions.
@@ -112,3 +126,35 @@ func TestPermissionsSchemaEnumMatchesConstants(t *testing.T) {
 		}
 	}
 }
+
+// TestOrganizationCustomRolePermissionsValidateAgainstSchema is a regression test that
+// ensures workflow frontmatter using the organization-custom-org-roles and
+// organization-custom-repository-roles permission scopes validates cleanly against the
+// JSON Schema, and that invalid values for these scopes are still rejected.
+func TestOrganizationCustomRolePermissionsValidateAgainstSchema(t *testing.T) {
+	for _, scope := range []string{"organization-custom-org-roles", "organization-custom-repository-roles"} {
+		t.Run(scope+"/valid", func(t *testing.T) {
+			frontmatter := map[string]any{
+				"on": "workflow_dispatch",
+				"permissions": map[string]any{
+					scope: "read",
+				},
+			}
+			if err := parser.ValidateMainWorkflowFrontmatterWithSchemaAndLocation(frontmatter, "workflow.md"); err != nil {
+				t.Fatalf("expected %q permission scope to validate cleanly, got error: %v", scope, err)
+			}
+		})
+
+		t.Run(scope+"/invalid-value", func(t *testing.T) {
+			frontmatter := map[string]any{
+				"on": "workflow_dispatch",
+				"permissions": map[string]any{
+					scope: "not-a-real-value",
+				},
+			}
+			if err := parser.ValidateMainWorkflowFrontmatterWithSchemaAndLocation(frontmatter, "workflow.md"); err == nil {
+				t.Fatalf("expected invalid value for %q permission scope to be rejected", scope)
+			}
+		})
+	}
+}