Skip to content

docs: warn about actions: read + setup-cli ordering when using gh aw logs/gh aw audit as workflow steps#22815

Merged
pelikhan merged 2 commits intomainfrom
copilot/clarify-gh-aw-extension-install
Mar 25, 2026
Merged

docs: warn about actions: read + setup-cli ordering when using gh aw logs/gh aw audit as workflow steps#22815
pelikhan merged 2 commits intomainfrom
copilot/clarify-gh-aw-extension-install

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 25, 2026

Using gh aw logs or gh aw audit as steps in a generated workflow silently fails with unknown command "aw" for "gh" if the setup-cli install step hasn't run yet, and with permission errors if actions: read is absent.

Changes

  • .github/aw/debug-agentic-workflow.md — Added [!IMPORTANT] callout after the "Key Commands Available" list with a YAML example showing the required permissions: actions: read and setup-cli step ordering.
  • .github/aw/github-agentic-workflows.md — Added ⚠️ IMPORTANT warning at the top of the "Logs and Metrics" section (primary gh aw logs docs) with the same YAML pattern.
  • .github/aw/runbooks/workflow-health.md — Added a note clarifying that the CLI commands shown target local/developer use, with a cross-reference for the workflow-step case.

Required pattern when using these commands as workflow steps

permissions:
  actions: read

steps:
  - name: Install gh-aw
    uses: github/gh-aw/actions/setup-cli@<version>
    with:
      version: <version>
  - name: Download logs
    run: gh aw logs ...   # Must come after setup-cli

Warning

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
    • Triggering command: /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 GO111MODULE 64/pkg/tool/linu--show-toplevel git rev-�� --show-toplevel 64/pkg/tool/linu^remote\..*\.gh-resolved$ /usr/bin/git -json GO111MODULE 64/pkg/tool/linu--show-toplevel git (http block)
  • https://api.github.com/orgs/test-owner/actions/secrets
    • Triggering command: /usr/bin/gh gh api /orgs/test-owner/actions/secrets --jq .secrets[].name --check **/*.cjs 64/bin/go **/*.json --ignore-path ../../../.pretti-bool go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
  • https://api.github.com/repos/actions/ai-inference/git/ref/tags/v1
    • Triggering command: /usr/bin/gh gh api /repos/actions/ai-inference/git/ref/tags/v1 --jq .object.sha --show-toplevel x_amd64/vet /opt/hostedtoolcache/node/24.14.0/x64/bin/node -json GO111MODULE x_amd64/vet node /tmp�� /home/REDACTED/work/gh-aw/gh-aw/.github/workflows/artifacts-summary.md x_amd64/vet /usr/bin/infocmp -json GO111MODULE x_amd64/vet infocmp (http block)
  • https://api.github.com/repos/actions/checkout/git/ref/tags/v3
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v3 --jq .object.sha 3015111/b438/_pkg_.a -buildtags 3015111/b438=&gt; -errorsas -ifaceassert -nilfunc /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/compile -o ithub-script/git/ref/tags/v8 -trimpath /usr/bin/git -p main -lang=go1.25 git (http block)
  • https://api.github.com/repos/actions/checkout/git/ref/tags/v5
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE .cfg GOINSECURE GOMOD GOMODCACHE ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha needs.build.outputs.version x_amd64/vet /usr/bin/git -json GO111MODULE 64/pkg/tool/linu--show-toplevel git rev-�� --show-toplevel 64/pkg/tool/linu-dwarf=false /usr/bin/git -json .cfg 64/pkg/tool/linu--show-toplevel git (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v5 --jq .object.sha --show-toplevel ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet /usr/bin/git -json GO111MODULE ache/go/1.25.0/x--show-toplevel git rev-�� --show-toplevel ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet 0/x64/bin/node -json GO111MODULE ache/go/1.25.0/x--show-toplevel git (http block)
  • https://api.github.com/repos/actions/checkout/git/ref/tags/v6
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha -test.paniconexit0 -test.v=true /usr/lib/git-core/git -test.timeout=10git -test.run=^Test -test.short=true--show-toplevel /usr/lib/git-core/git main�� nt/action/git/ref/tags/v999.999.999 --auto /usr/bin/git --detach GO111MODULE x_amd64/vet git (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha /tmp/go-build1973015111/b447/timeutil.test -importcfg /usr/bin/git -s -w -buildmode=exe git chec�� .github/workflows/test.md -extld=gcc /opt/hostedtoolcache/node/24.14.0/x64/bin/node -json GO111MODULE x_amd64/vet node (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/checkout/git/ref/tags/v6 --jq .object.sha --show-toplevel ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet /usr/bin/git -json GO111MODULE ache/go/1.25.0/x--show-toplevel git rev-�� --show-toplevel ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet /usr/bin/git 3742-28223/test-git GO111MODULE ache/go/1.25.0/x--show-toplevel git (http block)
  • https://api.github.com/repos/actions/github-script/git/ref/tags/v8
    • Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha k/gh-aw/gh-aw/pkGOSUMDB k/gh-aw/gh-aw/pkGOWORK 64/bin/go **/*.json --ignore-path ../../../.pretti-bool /opt/hostedtoolc-buildtags -o /tmp/go-build276-errorsas -trimpath 64/bin/go -p github.com/githu-atomic -lang=go1.25 go (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha /tmp/go-build2764833104/b418/_pkGOINSECURE -trimpath 64/bin/go -p main -lang=go1.25 go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
    • Triggering command: /usr/bin/gh gh api /repos/actions/github-script/git/ref/tags/v8 --jq .object.sha /tmp/go-build276-errorsas -trimpath 64/bin/go -p main -lang=go1.25 go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
  • https://api.github.com/repos/actions/setup-go/git/ref/tags/v4
    • Triggering command: /usr/bin/gh gh api /repos/actions/setup-go/git/ref/tags/v4 --jq .object.sha -bool -buildtags /usr/bin/git -errorsas -ifaceassert -nilfunc git -C /tmp/gh-aw-test-runs/20260325-013742-28223/test-148455027 rev-parse /usr/bin/git @{u} GO111MODULE x_amd64/vet git (http block)
  • https://api.github.com/repos/actions/setup-node/git/ref/tags/v4
    • Triggering command: /usr/bin/gh gh api /repos/actions/setup-node/git/ref/tags/v4 --jq .object.sha /tmp/TestHashConsistency_GoAndJavaScript1469599329/001/test-fronnonexistent/repo go /usr/bin/git -json GO111MODULE x_amd64/vet git rev-�� --show-toplevel x_amd64/vet /usr/bin/git -json GO111MODULE x_amd64/vet git (http block)
  • https://api.github.com/repos/actions/upload-artifact/git/ref/tags/v4
    • Triggering command: /usr/bin/gh gh api /repos/actions/upload-artifact/git/ref/tags/v4 --jq .object.sha -unreachable=false /tmp/go-build1973015111/b060/vet.cfg 3015111/b353/vet.cfg ck &#39;scripts/**/*git GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� ithub-script/git/ref/tags/v8 /tmp/go-build1973015111/b220/vet.cfg ache/node/24.14.0/x64/bin/node -json GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.0.0
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.0.0 --jq .object.sha -unreachable=false /tmp/go-build1973015111/b089/vet.cfg 3015111/b363/vet.cfg ck &#39;scripts/**/*git GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� -unreachable=false /tmp/go-build1973015111/b241/vet.cfg 3015111/b438/stringutil.test -json GO111MODULE 64/bin/go 3015111/b438/stringutil.test (http block)
  • https://api.github.com/repos/github/gh-aw-actions/git/ref/tags/v1.2.3
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw-actions/git/ref/tags/v1.2.3 --jq .object.sha 3742-28223/test-148455027 /tmp/go-build1973015111/b084/vet.cfg 3015111/b326/vet.cfg l GO111MODULE 64/bin/go /opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -uns�� k/gh-aw/gh-aw/.github/workflows /tmp/go-build1973015111/b238/vet.cfg ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet -json GO111MODULE 64/bin/go ache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/1/artifacts
    • Triggering command: /usr/bin/gh gh run download 1 --dir test-logs/run-1 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/12345/artifacts
    • Triggering command: /usr/bin/gh gh run download 12345 --dir test-logs/run-12345 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet estl�� -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/12346/artifacts
    • Triggering command: /usr/bin/gh gh run download 12346 --dir test-logs/run-12346 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/2/artifacts
    • Triggering command: /usr/bin/gh gh run download 2 --dir test-logs/run-2 GO111MODULE x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/3/artifacts
    • Triggering command: /usr/bin/gh gh run download 3 --dir test-logs/run-3 GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json .cfg x_amd64/link GOINSECURE GOMOD GOMODCACHE x_amd64/link (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/4/artifacts
    • Triggering command: /usr/bin/gh gh run download 4 --dir test-logs/run-4 GO111MODULE x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/actions/runs/5/artifacts
    • Triggering command: /usr/bin/gh gh run download 5 --dir test-logs/run-5 GO111MODULE x_amd64/link GOINSECURE GOMOD GOMODCACHE x_amd64/link env -json .cfg x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile (http block)
  • https://api.github.com/repos/github/gh-aw/actions/workflows
    • Triggering command: /usr/bin/gh gh workflow list --json name,state,path &#34;prettier&#34; --cheGOSUMDB /bin/sh 64/bin/go echo &#34;��� Patche/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
    • Triggering command: /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 GOMOD GOMODCACHE go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
    • Triggering command: /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 GOMOD GOMODCACHE 64/pkg/tool/linurev-parse env -json .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.0.0
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.0.0 --jq .object.sha -json .cfg At,event,headBranch,headSha,displayTitle GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env -json GO111MODULE 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/git/ref/tags/v1.2.3
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v1.2.3 --jq .object.sha -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go env -json GO111MODULE x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile (http block)
  • https://api.github.com/repos/github/gh-aw/git/ref/tags/v2.0.0
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v2.0.0 --jq .object.sha -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
  • https://api.github.com/repos/github/gh-aw/git/ref/tags/v3.0.0
    • Triggering command: /usr/bin/gh gh api /repos/github/gh-aw/git/ref/tags/v3.0.0 --jq .object.sha -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go env -json GO111MODULE x_amd64/vet GOINSECURE GOMOD GOMODCACHE x_amd64/vet (http block)
  • https://api.github.com/repos/nonexistent/action/git/ref/tags/v999.999.999
    • Triggering command: /usr/bin/gh gh api /repos/nonexistent/action/git/ref/tags/v999.999.999 --jq .object.sha ty-test.md .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env ithout_min-integrity3085529364/001 GO111MODULE x_amd64/compile GOINSECURE GOMOD GOMODCACHE x_amd64/compile (http block)
  • https://api.github.com/repos/nonexistent/repo/actions/runs/12345
    • Triggering command: /usr/bin/gh gh run view 12345 --repo nonexistent/repo --json status,conclusion GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet env 3282274290/.github/workflows .cfg 64/pkg/tool/linux_amd64/vet GOINSECURE GOMOD GOMODCACHE 64/pkg/tool/linux_amd64/vet (http block)
  • https://api.github.com/repos/owner/repo/actions/workflows
    • Triggering command: /usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go echo &#34;��� Go cod/opt/hostedtoolcache/go/1.25.0/x64/pkg/tool/linux_amd64/vet (http block)
    • Triggering command: /usr/bin/gh gh workflow list --json name,state,path --repo owner/repo 64/bin/go tierignore format:cjs 64/bin/go go env -json GO111MODULE 64/bin/go GOINSECURE GOMOD GOMODCACHE go (http block)
  • https://api.github.com/repos/owner/repo/contents/file.md
    • Triggering command: /tmp/go-build1973015111/b402/cli.test /tmp/go-build1973015111/b402/cli.test -test.testlogfile=/tmp/go-build1973015111/b402/testlog.txt -test.paniconexit0 -test.v=true -test.parallel=4 -test.timeout=10m0s -test.run=^Test -test.short=true GOSUMDB GOWORK 64/bin/go /opt/hostedtoolc-buildtags -o /tmp/go-build276-errorsas -trimpath 64/bin/go -p main -lang=go1.25 go (http block)
  • https://api.github.com/repos/test-owner/test-repo/actions/secrets
    • Triggering command: /usr/bin/gh gh api /repos/test-owner/test-repo/actions/secrets --jq .secrets[].name k/gh-aw/gh-aw/pkGOSUMDB k/gh-aw/gh-aw/pkGOWORK 64/bin/go **/*.json --ignore-path ../../../.pretti-bool /opt/hostedtoolc-buildtags -o /tmp/go-build276-errorsas -trimpath 64/bin/go -p main -lang=go1.25 go (http block)

If you need me to access, download, or install something from one of these locations, you can either:


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

…r gh aw logs/audit workflow steps

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f48ba19b-7de5-48ed-8f28-38de57b51ea9
Copilot AI changed the title [WIP] Document requirement for gh aw extension installation docs: warn about actions: read + setup-cli ordering when using gh aw logs/gh aw audit as workflow steps Mar 25, 2026
Copilot AI requested a review from pelikhan March 25, 2026 01:41
@pelikhan pelikhan marked this pull request as ready for review March 25, 2026 01:56
Copilot AI review requested due to automatic review settings March 25, 2026 01:56
@pelikhan pelikhan merged commit d668e0d into main Mar 25, 2026
45 checks passed
@pelikhan pelikhan deleted the copilot/clarify-gh-aw-extension-install branch March 25, 2026 01:56
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds documentation warnings clarifying that gh aw logs / gh aw audit will fail when used as workflow steps unless actions: read is granted and the setup-cli install step runs before any gh aw invocation.

Changes:

  • Added prominent warnings (callout/IMPORTANT blocks) describing required permissions: actions: read and setup-cli ordering.
  • Added a cross-reference note in the workflow health runbook clarifying local-vs-workflow-step usage.
  • Included a YAML pattern example for the required permissions + install ordering.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File Description
.github/aw/debug-agentic-workflow.md Adds an IMPORTANT callout explaining required permissions and setup-cli ordering for workflow-step usage.
.github/aw/github-agentic-workflows.md Adds an IMPORTANT warning at the primary gh aw logs docs location with the same pattern/example.
.github/aw/runbooks/workflow-health.md Adds a note clarifying the listed commands are local/agent-session oriented and links to the workflow-step guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +2152 to +2157
```yaml
permissions:
actions: read

steps:
- name: Install gh-aw
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The YAML example here isn’t valid GitHub Actions workflow YAML as written (steps: can’t be top-level; it must be nested under a job). Since this section refers to using gh aw logs/gh aw audit as steps inside a generated workflow, consider either (a) showing the minimal valid jobs:<job>:steps: structure, or (b) explicitly stating this snippet is for the agentic workflow frontmatter steps: field (not the compiled .lock.yml).

Copilot uses AI. Check for mistakes.
Comment on lines +76 to +82
> steps:
> - name: Install gh-aw
> uses: github/gh-aw/actions/setup-cli@<version>
> with:
> version: <version>
> - name: Download logs
> run: gh aw logs ...
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This YAML snippet reads like it should be pasted into a GitHub Actions workflow, but it isn’t valid Actions YAML as shown (steps: can’t be top-level). Since the surrounding text says “as steps inside a generated workflow”, consider updating the example to include the minimal jobs:<job>:steps: wrapper, or clarify that this is intended as agentic workflow frontmatter (permissions: + frontmatter steps:) rather than the compiled .lock.yml.

Suggested change
> steps:
> - name: Install gh-aw
> uses: github/gh-aw/actions/setup-cli@<version>
> with:
> version: <version>
> - name: Download logs
> run: gh aw logs ...
> jobs:
> debug-aw:
> runs-on: ubuntu-latest
> steps:
> - name: Install gh-aw
> uses: github/gh-aw/actions/setup-cli@<version>
> with:
> version: <version>
> - name: Download logs
> run: gh aw logs ...

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Steps using gh aw must always follow extension install (document/clarify in templates and docs)

3 participants