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

[mhavelock]

Problem

If a workflow generated by gh-aw places a step using gh aw logs before the extension install, the workflow fails with:

unknown command "aw" for "gh"

This can happen if a user edits the generated workflow or adds new steps without realizing the gh-aw extension is not globally available by default. The main source file for the workflow (.github/workflows/portfolio-analyst.md at https://github.com/github/gh-aw/blob/a0c0a8183fd045c9f3187bda167770d8897bd527/.github/workflows/portfolio-analyst.md) does not currently make this dependency explicit in a visible docstring or comment.

How to Reproduce

• In a workflow, put a step like this before installing the extension:

  - name: Download logs from last 30 days
    run: gh aw logs ...
  - name: Install gh-aw extension
    run: gh extension install github/gh-aw

• The workflow will fail when it reaches the first step above.

Suggestion

• Update documentation in .github/workflows/portfolio-analyst.md and other relevant templates to explicitly warn that all steps depending on gh aw must come after the extension install step.
• Consider generating workflows or additional comments that highlight this ordering dependency.
• Optionally, add a pre-step check or code comment to help users avoid this error in the future.

Impact

• Easy for new users to hit, since the order isn't always obvious.
• Trivial to fix, but frustrating if you don't realize the requirement.

---

This issue was originally encountered downstream in mhavelock/anthropicprinciple, but applies to all workflows generated by or derived from gh-aw configs.

---

Labels: workflow, bug, documentation

Note: I can also clone github/gh-aw to local to assist with any patch or PR if needed.

[mhavelock]

Update: root cause confirmed + working fix

After deeper investigation, there are two root causes — not just step ordering. Sharing full findings here in case useful for maintainers.

Root cause 1: extension resolution fails across shell steps

Even with correct step ordering (logs step after Install), using in a subsequent step fails with . The gh extension resolution system doesn't reliably propagate across shell steps on ubuntu-latest runners due to PATH/timing issues.

The Install step already handles this — it explicitly copies the binary to /opt/gh-aw/gh-aw for exactly this reason (and uses it internally for the MCP container). The fix is to call the binary directly:

# Before (fails):
run: gh aw logs --start-date -30d -c 5000 -o /tmp/portfolio-logs --json > /tmp/portfolio-logs/summary.json

# After (works):
run: /opt/gh-aw/gh-aw logs --start-date -30d -c 5000 -o /tmp/portfolio-logs --json > /tmp/portfolio-logs/summary.json

This matches the pattern used internally by the compiled workflow's MCP container at /opt/gh-aw/gh-aw — so it's consistent with gh-aw's own architecture.

Root cause 2: Missing actions: read permission on the agent job

The gh aw logs command fetches workflow run data via the GitHub API, which requires actions: read. The portfolio-analyst.md source specifies this permission, but gh aw compile v0.45.4 omitted it from the compiled agent job's permissions block.

Fix:

  agent:
    permissions:
      actions: read   # ← was missing from compiled output
      contents: read
      issues: read
      pull-requests: read

Note: actions: read was already correctly present on the activation job — only the agent job was missing it.

Verification

Both fixes applied to mhavelock/anthropicprinciple@b0e5932. The workflow ran successfully end-to-end (all 7 jobs: activation → agent → detection → update_cache_memory → safe_outputs → upload_assets → conclusion) on run 23376253616.

Suggestion for maintainers

1. Compiler bug: gh aw compile should propagate actions: read to the agent job when gh aw logs is used in the workflow source.
2. Template fix: The Download logs from last 30 days step in the portfolio-analyst template should use /opt/gh-aw/gh-aw logs rather than gh aw logs — since the binary is already available at that path after the Install step and is more reliable than extension resolution.
3. Docs: Noting that gh aw (extension invocation) and /opt/gh-aw/gh-aw (direct binary) behave differently across shell steps would help users debugging similar issues.

[mhavelock]

WARNING:

Copilot explained the issue and Claude & Gemini have updated it. I have tested and it's working well. I do not have the expertise to understand these changes fully - please BE WARNED.

• There are iterations mainly due to human error - i had the wrong branch set for testing.