CI Coach workflow uses invalid 'copilot-requests' permission: root cause analysis and remediation plan

[grahame-white]

Analysis

Error Recap

The CI validator reports this error when validating the .github/workflows/ci-coach.lock.yml workflow file:

The workflow is not valid. .github/workflows/ci-coach.lock.yml (Line: 259, Col: 7): The permission 'copilot-requests' is not allowed

Root Cause Investigation

1. GitHub Actions Permission Model

   • GitHub Actions supports a fixed set of permissions for jobs and workflows, documented at https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs.
   • Each permission must be one allowed by GitHub. Custom, arbitrary, or internal names are not accepted.

2. copilot-requests Permission

   • There is no documented permission named copilot-requests in GitHub Actions' permissions model (as of March 2026).
   • The only supported permissions include scopes like contents, pull-requests, issues, etc (see full list in GitHub docs).

3. How Did 'copilot-requests' Get Introduced?

   • Either the workflow YAML or a workflow compilation step (i.e., the ci-coach.lock.yml file, possibly auto-generated from a markdown workflow) is declaring permissions: copilot-requests: ... under a workflow or job section.
   • It is likely that during workflow authoring or conversion, an invalid permission name was specified—perhaps as a typo, a speculative scope, or due to a misunderstanding of available permissions, or because of copy-pasta from older or non-standard Copilot workflow content.

4. Actions Validator Behavior

   • The validator enforces the allowed set of permissions strictly. Any unknown permission triggers this error, blocking workflow runs or merges in repos with strict policies.

Why This Happened

• There is no copilot-requests permission in official GitHub Actions permissions. Its use indicates a documentation gap, mistaken assumption, or improper copying from somewhere else.
• If converting a markdown workflow to .lock.yml, it suggests the toolchain allows or does not warn about invalid permission scopes, letting the error slip through to workflow validation.
• If hand-edited, it may be legacy or accidental entry.

Impact

• The workflow fails validation and cannot run or be merged if workflows are checked strictly.
• This may block CI, automation, or deployments relying on the CI Coach workflow.

Proposed Remediation Plan

1. Locate every use of permissions: copilot-requests: ... in both the markdown source(s) and the compiled .lock.yml.
2. Remove or replace copilot-requests with only valid permission scopes, per GitHub documentation.
   • If Copilot API or workflow context is needed, check if contents or openId-related scopes are required instead. (There is no copilot-requests scope as of this writing.)
3. If generated by a tool:
   • Update the workflow generation logic to warn about and block non-standard permission scopes that are not part of the documented set.
4. Recompile and validate:
   • Rerun the workflow generator (e.g., gh aw compile) and commit updated workflows.
   • Validate that no invalid permission scopes remain.
5. Document:
   • Update any developer docs and CONTRIBUTING.md to remind contributors to only use documented GitHub Actions permissions.

References

• GitHub Actions permissions docs
• CONTRIBUTING.md (community and CI guidelines)

[grahame-white]

Root Cause Analysis: copilot-requests: write injected into compiled workflow permissions

Summary

gh aw compile unconditionally injects copilot-requests: write into the top-level permissions block of any workflow compiled with the features.copilot-requests feature flag enabled. copilot-requests is not a valid GitHub Actions permission scope, causing every such workflow to be rejected at runtime by the GitHub Actions validator with:

The permission 'copilot-requests' is not allowed

---

Precise call chain

1. Feature flag definition — pkg/constants/constants.go

// CopilotRequestsFeatureFlag is the feature flag name for enabling copilot-requests mode.
// When enabled: no secret validation step is generated, copilot-requests: write permission is added,
// and the GitHub Actions token is used as the agentic engine secret.
CopilotRequestsFeatureFlag FeatureFlag = "copilot-requests"

gh-aw/pkg/constants/constants.go

Lines 657 to 661 in 2a255d2

	// MCPScriptsFeatureFlag is the name of the feature flag for mcp-scripts
	MCPScriptsFeatureFlag FeatureFlag = "mcp-scripts"
	// MCPGatewayFeatureFlag is the feature flag name for enabling MCP gateway
	MCPGatewayFeatureFlag FeatureFlag = "mcp-gateway"
	// DisableXPIAPromptFeatureFlag is the feature flag name for disabling XPIA prompt

2. Permission constant — pkg/workflow/permissions.go

PermissionCopilotRequests is defined alongside all other scopes but is deliberately excluded from GetAllPermissionScopes(), which returns only the scopes that GitHub Actions actually recognises:

// PermissionCopilotRequests is a GitHub Actions permission scope used with the copilot-requests feature.
PermissionCopilotRequests PermissionScope = "copilot-requests"

// GetAllPermissionScopes returns all available permission scopes
func GetAllPermissionScopes() []PermissionScope {
    return []PermissionScope{
        PermissionActions,
        // ... (17 other real scopes)
        // PermissionCopilotRequests is NOT in this list
    }
}

gh-aw/pkg/workflow/permissions.go

Lines 75 to 119 in 2a255d2

	PermissionDiscussions PermissionScope = "discussions"
	PermissionIdToken PermissionScope = "id-token"
	PermissionIssues PermissionScope = "issues"
	PermissionMetadata PermissionScope = "metadata"
	PermissionModels PermissionScope = "models"
	PermissionPackages PermissionScope = "packages"
	PermissionPages PermissionScope = "pages"
	PermissionPullRequests PermissionScope = "pull-requests"
	PermissionRepositoryProj PermissionScope = "repository-projects"
	PermissionOrganizationProj PermissionScope = "organization-projects"
	PermissionSecurityEvents PermissionScope = "security-events"
	PermissionStatuses PermissionScope = "statuses"
	// PermissionCopilotRequests is a GitHub Actions permission scope used with the copilot-requests feature.
	// It enables use of the GitHub Actions token as the Copilot authentication token.
	PermissionCopilotRequests PermissionScope = "copilot-requests"
	)
	// GetAllPermissionScopes returns all available permission scopes
	func GetAllPermissionScopes() []PermissionScope {
	return []PermissionScope{
	PermissionActions,
	PermissionAttestations,
	PermissionChecks,
	PermissionContents,
	PermissionDeployments,
	PermissionDiscussions,
	PermissionIdToken,
	PermissionIssues,
	PermissionMetadata,
	PermissionModels,
	PermissionPackages,
	PermissionPages,
	PermissionPullRequests,
	PermissionRepositoryProj,
	PermissionOrganizationProj,
	PermissionSecurityEvents,
	PermissionStatuses,
	}
	}
	// Permissions represents GitHub Actions permissions
	// It can be a shorthand (read-all, write-all, read, write, none) or a map of scopes to levels
	// It can also have an "all" permission that expands to all scopes
	type Permissions struct {
	shorthand string

3. Injection site — pkg/workflow/tools.go → applyDefaults()

When CopilotRequestsFeatureFlag is detected on the workflow data, the compiler unconditionally calls perms.Set(PermissionCopilotRequests, PermissionWrite) and writes the result back to data.Permissions:

// When the copilot-requests feature is enabled, inject copilot-requests: write permission.
if isFeatureEnabled(constants.CopilotRequestsFeatureFlag, data) {
    perms := NewPermissionsParser(data.Permissions).ToPermissions()
    perms.Set(PermissionCopilotRequests, PermissionWrite)
    yaml := perms.RenderToYAML()
    // ... indent normalisation ...
    data.Permissions = strings.Join(lines, "\n")
}

gh-aw/pkg/workflow/tools.go

Lines 193 to 210 in 2a255d2

	// When the copilot-requests feature is enabled, inject copilot-requests: write permission.
	// This is required so that the GitHub Actions token has the necessary scope
	// to authenticate with the Copilot API.
	if isFeatureEnabled(constants.CopilotRequestsFeatureFlag, data) {
	perms := NewPermissionsParser(data.Permissions).ToPermissions()
	perms.Set(PermissionCopilotRequests, PermissionWrite)
	yaml := perms.RenderToYAML()
	// Adjust from job-level indentation (6 spaces) to workflow-level (2 spaces)
	lines := strings.Split(yaml, "\n")
	for i := 1; i < len(lines); i++ {
	if strings.HasPrefix(lines[i], " ") {
	lines[i] = " " + lines[i][6:]
	}
	}
	data.Permissions = strings.Join(lines, "\n")
	}
	return nil

There is also a guard that forces the empty-permissions ({}) path to fall through to this block, meaning even a workflow that explicitly requests no permissions will have copilot-requests: write injected:

// Exception: if copilot-requests feature is enabled, we still need to fall through
// so the injection block below can add copilot-requests: write.
if data.Permissions == "permissions: {}" && !isFeatureEnabled(constants.CopilotRequestsFeatureFlag, data) {
    return nil
}

gh-aw/pkg/workflow/tools.go

Lines 163 to 168 in 2a255d2

	// In this case, we should NOT apply default read-all.
	// Exception: if copilot-requests feature is enabled, we still need to fall through
	// so the injection block below can add copilot-requests: write.
	if data.Permissions == "permissions: {}" && !isFeatureEnabled(constants.CopilotRequestsFeatureFlag, data) {
	// Explicitly empty permissions - preserve the empty state
	// The agent job in dev mode will add contents: read if needed for local actions

4. Local schema patch masks the problem — Makefile

The patch-github-actions-schema target adds copilot-requests to the local copy of the GitHub Actions JSON schema, so editor/local validation tools pass without error. This masks the defect until the workflow is pushed and GitHub's own validator runs:

patch-github-actions-schema:
    @echo "Patching GitHub Actions schema with copilot-requests permission..."
    @tmpfile=$$(mktemp) && \
        jq '.definitions["permissions-event"].properties["copilot-requests"] = {"type": "string", "enum": ["write", "none"]}' \
            pkg/workflow/schemas/github-workflow.json > "$$tmpfile" && \
        mv "$$tmpfile" pkg/workflow/schemas/github-workflow.json

gh-aw/Makefile

Lines 484 to 493 in 2a255d2

	patch-github-actions-schema:
	@echo "Patching GitHub Actions schema with copilot-requests permission..."
	@tmpfile=$$(mktemp) && \
	jq '.definitions["permissions-event"].properties["copilot-requests"] = {"type": "string", "enum": ["write", "none"]}' \
	pkg/workflow/schemas/github-workflow.json > "$$tmpfile" && \
	mv "$$tmpfile" pkg/workflow/schemas/github-workflow.json
	@cd actions/setup/js && npm run format:schema >/dev/null 2>&1
	@echo "✓ Patched GitHub Actions schema with copilot-requests permission"
	# Run linter (full repository scan)

5. Intent was already acknowledged as stale — .changeset/patch-merge-detection-job.md

A changeset entry explicitly notes that the copilot-requests permission schema entry is unused and should be removed, but the compiler injection was not cleaned up at the same time:

Merged the detection job into the action job so the detection steps run inline
with the main workflow and removed the unused `copilot-requests` permission schema entry.

https://github.com/github/gh-aw/blob/2a255d2b0860092c74d8bb7f86713b6393424f40/.changeset/patch-merge-detection-job.md

---

Why copilot-requests is not a valid Actions scope

GitHub Actions validates permissions: blocks against a fixed allow-list of scopes (see Assigning permissions to jobs). copilot-requests does not appear in that list and has never been a supported scope. The token-based Copilot authentication flow this feature was designed to support uses ${{ github.token }} at runtime; no special permission scope is required or recognised by the platform.

---

Proposed remediation

#	Location	Action
1	pkg/workflow/tools.go applyDefaults()	Remove the isFeatureEnabled(CopilotRequestsFeatureFlag) injection block entirely
2	pkg/workflow/tools.go	Remove the permissions: {} guard exception that exists solely for the injection block
3	pkg/workflow/permissions.go	Remove PermissionCopilotRequests constant and its case "copilot-requests": branch in convertStringToPermissionScope
4	Makefile	Remove the patch-github-actions-schema target and all callers; the schema patch is no longer needed
5	pkg/workflow/schemas/github-workflow.json	Re-download a clean copy of the schema (run make download-github-actions-schema without the patch step)
6	Tests	Add a compiler test asserting that no compiled output contains a permission scope not in GetAllPermissionScopes(), covering all feature-flag combinations

The copilot-requests execution-time behaviour (using ${{ github.token }} as COPILOT_GITHUB_TOKEN, setting S2STOKENS=true, skipping secret validation) in copilot_engine_execution.go and copilot_engine_installation.go is orthogonal and does not require the invalid permission scope — those paths can remain unchanged.