Common Issues | GitHub Agentic Workflows
Skip to main content Common Issues Frequently encountered issues, organized by workflow stage and component. Installation Issues Section titled “Installation Issues” Extension Installation Fails Section titled “Extension Installation Fails” If gh extension install github/gh-aw fails, use the standalone installer (works in Codespaces and restricted networks). Pass a tag as the second argument to pin a version ( releases ).
Verify with gh extension list . Terminal window curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s -- v0.40.0 Organization Policy Issues Section titled “Organization Policy Issues” Custom Actions Not Allowed in Enterprise Organizations Section titled “Custom Actions Not Allowed in Enterprise Organizations” Error: The action github/gh-aw/actions/setup@... is not allowed in {ORG} because all actions must be from a repository owned by your enterprise, created by GitHub, or verified in the GitHub Marketplace.
Cause: Enterprise policies restrict which GitHub Actions can be used. Solution: An admin must add github/gh-aw@* to the organization’s allowed actions, either through Settings → Actions → Policies → “Allow select actions and reusable workflows” ( docs ), or by editing a centralized policies/actions.yml : allowed_actions : - " actions/* " - " github/gh-aw@* " Wait a few minutes for policy propagation, then re-run.
Repository Configuration Issues Section titled “Repository Configuration Issues” Actions Restrictions Reported During Init Section titled “Actions Restrictions Reported During Init” The CLI validates three permission layers in Repository Settings → Actions → General: enable Actions, switch from local-only restrictions to allowing GitHub-created or all actions, and, if you’re using a selective allowlist, enable GitHub-created actions as well.
See the repository Actions settings docs and allowlist details . Copilot Pull Request Workflows Require Approval Section titled “Copilot Pull Request Workflows Require Approval” Symptom: Runs on a Copilot branch conclude with action_required without starting any jobs. This is an approval gate, not a test failure. Solution: Review the proposed changes, especially workflow changes, then select Approve and run workflows in the pull request’s merge box.
Changing a job’s if: condition, adding trusted-users , or granting token permissions cannot bypass this pre-execution gate. To reduce repeated approvals, a repository administrator can disable Require approval for workflow runs under Settings → Copilot → Cloud agent → Policies . This is a repository setting, not gh-aw frontmatter or an actor allowlist. See configuring automatic workflow runs . Workflow Compilation Issues Section titled “Workflow Compilation Issues” Frontmatter Field Not Taking Effect Section titled “Frontmatter Field Not Taking Effect” If a frontmatter setting appears to be silently ignored, the field name may be misspelled.
The compiler does not warn about unknown field names — they are silently discarded. Compilation Failures Section titled “Compilation Failures” Validate YAML syntax (especially indentation and key: value spacing), confirm required fields such as on: , and check types against the schema with gh aw compile --verbose . If no lock file is generated, fix the reported errors, confirm .github/workflows/ is writable, and remove stale .lock.yml files with gh aw compile --purge after deleting a workflow .md .
Import and Include Issues Section titled “Import and Include Issues” Import paths are relative to the repository root, for example .github/workflows/shared/tools.md ; verify the expected files with git status . A workflow can import only one file from .github/agents/ . If compilation hangs, check for circular imports and remove the cycle. Tool Configuration Issues Section titled “Tool Configuration Issues” GitHub Tools Not Available Section titled “GitHub Tools Not Available” Configure GitHub access with toolsets: ( tools reference ).
If a tool is still missing, combine toolsets such as toolsets: [default, actions] or inspect the resolved toolset with gh aw mcp inspect <workflow> . tools : github : toolsets : [ repos , issues ] MCP Server Connection Failures Section titled “MCP Server Connection Failures” Verify package installation, command syntax, and required environment variables: mcp-servers : my-server : command : " npx " args : [ " @myorg/mcp-server " ] env : API_KEY : " ${{ secrets.MCP_API_KEY }} " OpenCode MCP Tools Not Being Called Section titled “OpenCode MCP Tools Not Being Called” OpenCode-compatible engines do not auto-discover MCP servers, so declare them in an explicit opencode.jsonc .
MCP_GATEWAY_PORT and MCP_GATEWAY_AGENT_ID are expanded from workflow env at runtime; substitute concrete values outside a workflow: { "provider" : { "copilot-proxy" : { "api" : " http://host.docker.internal:10004 " , "options" : { "apiKey" : " awf-copilot-proxy " }, "models" : { "gpt-4.1" : {}, "claude-sonnet-4-6" : {} } } }, "model" : " copilot-proxy/claude-sonnet-4-6 " , "mcp" : { "safeoutputs" : { "type" : " http " , "url" : " http://host.docker.internal:${MCP_GATEWAY_PORT}/mcp/safeoutputs " , "headers" : { "Authorization" : " ${MCP_GATEWAY_AGENT_ID} " }, "disabled" : false , "timeout" : 30000 } }, "agent" : { "build" : { "permission" : { "bash" : " allow " , "edit" : " allow " , "read" : " allow " , "glob" : " allow " , "grep" : " allow " , "write" : " allow " , "external_directory" : " allow " } } } } Route MCP servers through URLs such as http://host.docker.internal:${MCP_GATEWAY_PORT}/mcp/<server-name> .
Use agent.build.permission (singular, not permissions ). Set external_directory: allow only when access outside the workspace is needed; the default ask acts as a deny in non-interactive runs. Do not append /v1 to direct Copilot endpoints ( api.githubcopilot.com ). For other OpenAI-compatible providers, use the documented base path so /chat/completions is appended correctly. With --enable-api-proxy , pass COPILOT_GITHUB_TOKEN in the execute step’s env: : - name : Execute env : COPILOT_GITHUB_TOKEN : ${{ steps.copilot-token.outputs.token }} run : | awf --enable-api-proxy <workflow-args> -- opencode run "<prompt>" Playwright Network Access Denied Section titled “Playwright Network Access Denied” Add domains to network.allowed : network : allowed : - github.com - " *.github.io " Cannot Find Module ‘playwright’ Section titled “Cannot Find Module ‘playwright’” Error: Cannot find module 'playwright' — the built-in tool installs @playwright/cli , not the Playwright JavaScript library.
Use playwright-cli commands instead of require('playwright') : Terminal window playwright-cli goto " https://example.com " playwright-cli snapshot See the Playwright reference for CLI commands and MCP migration guidance. Permission Issues Section titled “Permission Issues” Write Operations Fail Section titled “Write Operations Fail” All writes (issues, comments, PR updates) must go through the safe-outputs system — declare the types your workflow needs in frontmatter: safe-outputs : create-issue : title-prefix : " [bot] " labels : [ automation ] add-comment : # no configuration required; uses defaults update-issue : # no configuration required; uses defaults If an operation isn’t in the Safe Outputs reference , it may not be supported; see the Safe Outputs Specification .
Safe Outputs Not Creating Issues Section titled “Safe Outputs Not Creating Issues” Disable staged mode: safe-outputs : staged : false create-issue : title-prefix : " [bot] " labels : [ automation ] Project Field Type Errors Section titled “Project Field Type Errors” GitHub Projects reserves field names like REPOSITORY . Use alternatives ( repo , source_repository , linked_repo ): # ✗ Wrong: repository # ✓ Corre
The rest of this page is on the live site.