Add gh aw run guidance and CLI commands reference#28616
Conversation
- Add `gh aw run` to Quick Reference section in dispatcher agent template - Add 'Triggering runs' and 'CLI commands reference' bullets to Important Notes - Add CLI Commands Reference to Available Prompts list with dispatch route - Create .github/aw/cli-commands.md: comprehensive CLI reference covering all gh aw commands, CLI vs MCP tool selection, debugging scenarios, and a CLI ↔ MCP tool mapping table - Update github-agentic-workflows.md CLI section with gh aw run guidance and link to the new cli-commands.md Agent-Logs-Url: https://github.com/github/gh-aw/sessions/2ed0ad2e-a767-436c-bb68-dede4a661b4a Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
…T admonition Agent-Logs-Url: https://github.com/github/gh-aw/sessions/2ed0ad2e-a767-436c-bb68-dede4a661b4a Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
gh aw run guidance and CLI commands reference
There was a problem hiding this comment.
Pull request overview
Adds missing documentation and guidance to ensure agents and users trigger workflows via gh aw run (instead of gh workflow run <file>.lock.yml), and introduces a consolidated CLI↔MCP reference.
Changes:
- Added
gh aw runguidance to the main agentic workflows documentation and dispatcher agent template. - Introduced a new comprehensive CLI commands reference (
cli-commands.md) including CLI↔MCP mappings and debugging scenarios. - Linked the dispatcher routing and docs to the new reference material.
Show a summary per file
| File | Description |
|---|---|
| .github/aw/github-agentic-workflows.md | Adds a “Run a Workflow on Demand” section emphasizing gh aw run and links to the new CLI reference. |
| .github/aw/cli-commands.md | New consolidated CLI reference with examples, environment guidance (CLI vs MCP), and mapping table. |
| .github/agents/agentic-workflows.agent.md | Updates dispatcher routing and quick reference to include gh aw run and link to CLI reference. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 3/3 changed files
- Comments generated: 2
| gh aw compile # Compile all workflows | ||
| gh aw compile <workflow-name> # Compile a specific workflow | ||
| gh aw compile --strict # Compile with strict mode validation | ||
| gh aw compile --validate # Validate without emitting lock files |
There was a problem hiding this comment.
gh aw compile --validate is described here as "Validate without emitting lock files", but --validate only enables schema/image/action-SHA validation; emitting lock files is controlled by --no-emit. Update the examples to use --no-emit (optionally combined with --validate) and adjust the description accordingly.
| gh aw compile --validate # Validate without emitting lock files | |
| gh aw compile --validate # Enable schema/image/action-SHA validation | |
| gh aw compile --no-emit # Compile/validate without emitting lock files |
| gh aw run <workflow-name>.md # Alternative: explicit .md extension | ||
| gh aw run <workflow-name> --ref main # Run on a specific branch/tag/SHA | ||
| gh aw run <workflow-name> --repeat 3 # Run 4 times total (1 + 3 repeats) | ||
| gh aw run <workflow-name> --input key=value # Pass a specific input |
There was a problem hiding this comment.
gh aw run does not have a --input flag. The CLI uses -F key=value (aka --raw-field) for workflow inputs; please update this example to match the actual flag so users can copy/paste it successfully.
| gh aw run <workflow-name> --input key=value # Pass a specific input | |
| gh aw run <workflow-name> -F key=value # Pass a specific input |
The dispatcher agent template had no mention of
gh aw run, causing agents to default togh workflow run <file>.lock.yml— bypassing input validation, workflow resolution by short name, and run-tracking.Changes
.github/agents/agentic-workflows.agent.mdgh aw runbetweencompileandlogsgh aw run; nevergh workflow run <file>.lock.yml) and "CLI commands reference" linkcli-commands.md.github/aw/cli-commands.md(new)Comprehensive CLI reference covering:
agentic-workflowsMCP tool (Copilot Cloud, no-auth CI)gh awcommand with examples and MCP tool equivalentgh aw rungets a[!IMPORTANT]admonition and explicit fallback via GitHub MCPcreate_workflow_dispatchdebug-agentic-workflow.md.github/aw/github-agentic-workflows.mdgh aw runsubsection to the CLI sectioncli-commands.mdWarning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
https://api.github.com/graphql/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw(http block)/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw n_test.go .go on_test.go er tion_test.go(http block)/usr/bin/gh /usr/bin/gh api graphql -f query=query($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -f owner=github -f name=gh-aw _compile_test.goapi _defaults_test.ggraphql _error_codes_tes-f _fix�� json' --ignore-p-f _http.go _http_test.go _inspect_test.godocker _json_integratioimage _operations_testinspect _stdio_integratighcr.io/github/serena-mcp-server:latest(http block)https://api.github.com/orgs/test-owner/actions/secrets/usr/bin/gh gh api /orgs/test-owner/actions/secrets --jq .secrets[].name ithub/workflows man /home/node_modul-importcfg l -m 0755 node /hom�� --write erena-mcp-server-ifaceassert x_amd64/vet **/*.json --ignore-path ed } } x_amd64/vet(http block)https://api.github.com/repos/actions/ai-inference/git/ref/tags/v1/usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq [.object.sha, .object.type] | @tsv /tmp/TestCollectWorkflowFiles_WithImports708308469/001 config /usr/bin/git remote.origin.urgit d/gh-aw/capitalirev-parse ache/go/1.25.8/x--show-toplevel git rev-�� --show-toplevel ache/go/1.25.8/xtest@example.com /usr/bin/git graphql -f cfg git(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v3/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq [.object.sha, .object.type] | @tsv 2849-16177/test-1592614004 x_amd64/compile /opt/hostedtoolcache/node/24.14.1/x64/bin/node ithub/workflows(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v5/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv 001/noflag-a.md 348117/b215/vet.cfg x_amd64/vet --local atted/golang/pkg-1 $name) { hasxterm-color x_amd64/vet -uns�� 2849-16177/test-214989803 /tmp/go-build691348117/b020/vet.cfg 348117/b395=> celain --ignore-git(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv --show-toplevel ache/go/1.25.8/x64/pkg/tool/linux_amd64/vet /usr/bin/git se 348117/b216/vet.\n ache/go/1.25.8/x: git rev-�� --show-toplevel ache/go/1.25.8/xremote.origin.url /usr/bin/git se 348117/b375/vet.rev-parse ache/go/1.25.8/x--show-toplevel git(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq [.object.sha, .object.type] | @tsv --show-toplevel infocmp /usr/bin/git image:v1.0.0 /usr/lib/systemdrev-parse e/git git rev-�� --show-toplevel e/git /usr/bin/git --show-toplevel node /usr/bin/git git(http block)https://api.github.com/repos/actions/checkout/git/ref/tags/v6/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv ignore-path ../../../.prettierignore(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv --local user.email 1/x64/bin/npm(http block)/usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv --local user.name 64/bin/node(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v8/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq [.object.sha, .object.type] | @tsv --show-toplevel er.test /usr/bin/git t0 /tmp/go-build691/tmp/gh-aw-test-runs/20260426-172905-18866/test-patch-priority-22266�� e/git-receive-pack git rev-�� --show-toplevel(http block)https://api.github.com/repos/actions/github-script/git/ref/tags/v9/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv rite '../../../**/*.json' '!../.-f(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv --noprofile(http block)/usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v9 --jq [.object.sha, .object.type] | @tsv ithub/workflows(http block)https://api.github.com/repos/actions/setup-go/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv --git-dir 64/pkg/tool/linu-buildtags 348117/b468/vet.cfg k/gh-aw/gh-aw config 64/pkg/tool/linu--show-toplevel infocmp -1 xterm-color 64/pkg/tool/linurev-parse /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/compile y_only_defaults_git show cfg /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/compile(http block)https://api.github.com/repos/actions/setup-node/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv --show-toplevel sh /opt/hostedtoolcache/node/24.14.1/x64/bin/node ithub/workflows(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv secrets.TOKEN 64/pkg/tool/linu-test.v=true /usr/bin/infocmp k/gh-aw/gh-aw/.ggit cfg 64/pkg/tool/linu--show-toplevel infocmp -1 xterm-color 64/pkg/tool/linux_amd64/vet /usr/bin/infocmp k/gh-aw/gh-aw/.ggit rev-parse ache/go/1.25.8/x--show-toplevel infocmp(http block)https://api.github.com/repos/actions/setup-node/git/ref/tags/v6/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv --local user.email ml(http block)/usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v6 --jq [.object.sha, .object.type] | @tsv -bool -buildtags /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/vet -errorsas -ifaceassert -nilfunc /opt/hostedtoolcache/go/1.25.8/x64/pkg/tool/linux_amd64/vet -ato�� licyMinIntegrityOnlymin-integrity_with_explicit_repo1216120157/0remote.origin.url -buildtags /usr/bin/git l -ifaceassert -nilfunc git(http block)https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v4/usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq [.object.sha, .object.type] | @tsv -fhz/sg3YSHTzqdvJXL5t-fhz remote /usr/bin/git ithub/workflows(http block)https://api.github.com/repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b/usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq [.object.sha, .object.type] | @tsv(http block)/usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq [.object.sha, .object.type] | @tsv h ../../../.pret.prettierignore(http block)/usr/bin/gh gh api /repos/astral-sh/setup-uv/git/ref/tags/eac588ad8def6316056a12d4907a9d4d84ff7a3b --jq [.object.sha, .object.type] | @tsv h ../../../.prettierignore(http block)https://api.github.com/repos/github/gh-aw/usr/bin/gh gh api /repos/github/gh-aw --jq .default_branch */*.ts' '**/*.jsremote.origin.url committer.name r: $owner, name: $name) { hasDiscussionsEnabled } }(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v0.1.2/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v0.1.2 --jq [.object.sha, .object.type] | @tsv -1564039828/base.md -1564039828/new.md /usr/bin/git /home/REDACTED/worgit cfg x_amd64/link /usr/bin/git conf�� --get-regexp ^remote\..*\.gh-resolved$ /usr/bin/git k/gh-aw/gh-aw/.ggit -f 64/pkg/tool/linu--show-toplevel git(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.0.0/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.0.0 --jq [.object.sha, .object.type] | @tsv /tmp/TestGuardPolicyMinIntegrityOnlymin-integrity_only_defaults_@{u} 348117/b444/_testmain.go /usr/bin/git remote.origin.urgit --write me: String!) { --show-toplevel git rev-�� --show-toplevel node /usr/bin/git run format:pkg-json x_amd64/vet git(http block)https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.2.3/usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.2.3 --jq [.object.sha, .object.type] | @tsv 348117/b472/_pkg_.a node 348117/b472=> ithub/workflows --write /bin/sh git init�� poJ_/sX9FX53sm1OTZ6jdpoJ_ l /usr/bin/git ithub/workflows(http block)https://api.github.com/repos/github/gh-aw/actions/runs/1/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/1/artifacts --jq .artifacts[].name rev-parse 64/pkg/tool/linux_amd64/compile json' --ignore-pgit r $name) { has--show-toplevel 64/pkg/tool/linux_amd64/compile(http block)/usr/bin/gh gh run download 1 --dir test-logs/run-1 config tants.test l(http block)https://api.github.com/repos/github/gh-aw/actions/runs/12345/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/12345/artifacts --jq .artifacts[].name cfg 64/pkg/tool/linux_amd64/compile nt >/dev/null 2>git ame DiscussionsEnabluser.name 64/pkg/tool/linuTest User(http block)/usr/bin/gh gh run download 12345 --dir test-logs/run-12345 -f 64/pkg/tool/linux_amd64/vet -f owner=github -f 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/12346/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/12346/artifacts --jq .artifacts[].name config 64/pkg/tool/linux_amd64/compile remote.origin.urgit ame t[bot] 64/pkg/tool/linutest@example.com(http block)/usr/bin/gh gh run download 12346 --dir test-logs/run-12346 cfg 64/pkg/tool/linux_amd64/vet l ame DiscussionsEnabl--show-toplevel 64/pkg/tool/linux_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/actions/runs/2/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/2/artifacts --jq .artifacts[].name l_test.go 64/pkg/tool/linux_amd64/compile l r ps 64/pkg/tool/linux_amd64/compile(http block)/usr/bin/gh gh run download 2 --dir test-logs/run-2 l_test.go ache/go/1.25.8/x-nolocalimports(http block)https://api.github.com/repos/github/gh-aw/actions/runs/3/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/3/artifacts --jq .artifacts[].name cfg 64/pkg/tool/linu-importcfg json' --ignore-pgit r = get && echo "--show-toplevel 64/pkg/tool/linux_amd64/vet(http block)/usr/bin/gh gh run download 3 --dir test-logs/run-3 o 64/pkg/tool/linux_amd64/compile -f owner=github -f 64/pkg/tool/linux_amd64/compile(http block)https://api.github.com/repos/github/gh-aw/actions/runs/4/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/4/artifacts --jq .artifacts[].name(http block)/usr/bin/gh gh run download 4 --dir test-logs/run-4 config x_amd64/compile remote.origin.urgit(http block)https://api.github.com/repos/github/gh-aw/actions/runs/5/artifacts/usr/bin/gh gh api --paginate repos/{owner}/{repo}/actions/runs/5/artifacts --jq .artifacts[].name -f 64/pkg/tool/linux_amd64/compile -f owner=github -f 64/pkg/tool/linux_amd64/compile(http block)/usr/bin/gh gh run download 5 --dir test-logs/run-5 mcp/ast-grep:lat-nolocalimports x_amd64/compile(http block)https://api.github.com/repos/github/gh-aw/actions/workflows/usr/bin/gh gh workflow list --json name,state,path(http block)/usr/bin/gh gh run list --json databaseId,number,url,status,conclusion,workflowName,createdAt,startedAt,updatedAt,event,headBranch,headSha,displayTitle --workflow nonexistent-workflow-12345 --limit 100 --ignore-path ../../../.prettierignore x_amd64/vet rev-�� --git-dir(http block)/usr/bin/gh gh run list --json databaseId,number,url,status,conclusion,workflowName,createdAt,startedAt,updatedAt,event,headBranch,headSha,displayTitle --workflow nonexistent-workflow-12345 --limit 6(http block)https://api.github.com/repos/github/gh-aw/contents/.github/workflows/shared/reporting.md/tmp/go-build691348117/b404/cli.test /tmp/go-build691348117/b404/cli.test -test.testlogfile=/tmp/go-build691348117/b404/testlog.txt -test.paniconexit0 -test.v=true -test.parallel=4 -test.timeout=10m0s -test.run=^Test -test.short=true(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v0.47.4/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v0.47.4 --jq [.object.sha, .object.type] | @tsv --show-toplevel ache/go/1.25.8/x^remote\..*\.gh-resolved$ /usr/bin/git Onlymin-integritgit config 64/pkg/tool/linu--show-toplevel git rev-�� --show-toplevel 64/pkg/tool/linux_amd64/link /usr/bin/git eutil.test -trimpath rtcfg.link git(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.0.0 --jq [.object.sha, .object.type] | @tsv se 348117/b051/vet.cfg ck remote.origin.urgit --local r: $owner, name:--show-toplevel ache/go/1.25.8/x64/pkg/tool/linurev-parse sRem�� /home/REDACTED/work/gh-aw/gh-aw/.github/workflows config ache/go/1.25.8/x64/pkg/tool/linux_amd64/vet remote.origin.urgit --local /opt/pipx_bin/gi--show-toplevel ache/go/1.25.8/x64/pkg/tool/linuremote.origin.url(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.2.3/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.2.3 --jq [.object.sha, .object.type] | @tsv ithub/workflows erena-mcp-server-ifaceassert x_amd64/vet(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v2.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq [.object.sha, .object.type] | @tsv "prettier" --wri-c=4(http block)/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq [.object.sha, .object.type] | @tsv ithub/workflows(http block)/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq [.object.sha, .object.type] | @tsv k/gh-aw/gh-aw/.github/workflows ../../../**/*.json x_amd64/vet --ignore-path ../../../.prettirev-parse ndor/bin/git x_amd64/vet -C k/gh-aw/gh-aw/.github/workflows config x_amd64/vet remote.origin.urgit(http block)https://api.github.com/repos/github/gh-aw/git/ref/tags/v3.0.0/usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v3.0.0 --jq [.object.sha, .object.type] | @tsv(http block)https://api.github.com/repos/nonexistent/action/git/ref/tags/v999.999.999/usr/bin/gh gh api /repos/nonexistent/action/git/ref/tags/v999.999.999 --jq [.object.sha, .object.type] | @tsv 2370670123/001 348117/b061/vet.cfg cfg -f owner=github -f ache/go/1.25.8/x64/pkg/tool/linuremote(http block)https://api.github.com/repos/nonexistent/repo/actions/runs/12345/usr/bin/gh gh run view 12345 --repo nonexistent/repo --json status,conclusion l(http block)https://api.github.com/repos/owner/repo/actions/workflows/usr/bin/gh gh workflow list --json name,state,path --repo owner/repo repository(owner: $owner, name:-f(http block)/usr/bin/gh gh workflow list --json name,state,path --repo owner/repo /home/REDACTED/wor-nolocalimports(http block)/usr/bin/gh gh workflow list --repo owner/repo --json name,path,state 64/pkg/tool/linux_amd64/link th .prettierignogit --global $name) { hasuser.name 64/pkg/tool/linuTest User -1 erutil.test git rtcfg.link ../pkg/workflow/gh --local 1/x64/bin/npm 1TrQ_zyaDDimeco6repos/{owner}/{repo}/actions/runs/12346/artifacts(http block)https://api.github.com/repos/test-owner/test-repo/actions/secrets/usr/bin/gh gh api /repos/test-owner/test-repo/actions/secrets --jq .secrets[].name k/gh-aw/gh-aw security repository(owner: $owner, name: $name) { hasDiscussionsEnabled } } -nxv(http block)https://api.github.com/repos/test/repo/usr/bin/gh gh api /repos/test/repo --jq .default_branch /home/REDACTED/work/gh-aw/gh-aw/.github/workflows rev-parse cfg --get-regexp --local sh ache/go/1.25.8/x64/pkg/tool/linu-test.v=true(http block)If you need me to access, download, or install something from one of these locations, you can either: