Feature request: post-agent-steps section that runs after the safe_outputs job

[bryanchen-d]

Summary

Add a frontmatter section post-agent-steps: (mirror of the existing pre-agent-steps: and post-steps:) whose steps are injected into a new job that needs: [agent, safe_outputs] and runs after the safe_outputs job completes — with access to its outputs (e.g. push_commit_sha, push_commit_url, created_pr_number, code_push_failure_count, etc.).

Motivation

The current post-steps: block runs inside the agent job, before the safe_outputs job has had a chance to execute any safe outputs (push, create-PR, add-reviewer, etc.). That makes it impossible to:

• Run a side-effect only when a push actually happened this cycle.
• Run a side-effect only when the push succeeded.
• Pass the resulting commit SHA / PR URL to a downstream system (Slack, telemetry, internal queue).

Example use case from our errors-fix driver:

Re-request a Copilot review only after a push lands. We can't do it as a post-step because push_commit_sha doesn't exist there. We can't do it as a safe-output (add-reviewer) because of #35283. The current alternatives are (a) a separate workflow_run-triggered workflow file, which clutters .github/workflows/, or (b) accepting the flakiness.

Proposed shape

post-agent-steps:
  - name: Notify on successful push
    if: needs.safe_outputs.outputs.push_commit_sha != ''
    run: |
      curl ... "sha=${{ needs.safe_outputs.outputs.push_commit_sha }}"

Compile this into a new job:

post_agent:
  needs: [agent, safe_outputs]
  if: always()
  runs-on: ubuntu-latest
  steps: # ...user steps...

with all ${{ needs.safe_outputs.outputs.* }} references available.

Related

• Partner issue: add-reviewer safe-output: ignores target-repo + does not use GraphQL botIds for Copilot bot #35283 (add-reviewer ignores target-repo + wrong API surface for Copilot bot). Together the two would let us delete a manual workaround.

Environment

• gh-aw: v0.74.x

[pelikhan]

/scout create an example of the "jobs" frontmatter section showing how to implement this feature. Check that outputs are available.

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

The proposed post-agent-steps: shape can already be expressed today using the existing jobs: frontmatter section (see Custom Steps and Jobs). A custom job with needs: [agent, safe_outputs] runs after safe_outputs and can read every output that job exposes — confirmed against the compiler at pkg/workflow/compiler_safe_outputs_job.go:271-389. The two main gotchas: outputs are conditionally declared (e.g. push_commit_sha only appears when push-to-pull-request-branch: is configured), and you must set needs: explicitly — the compiler at pkg/workflow/compiler_jobs.go:513-865 auto-adds activation as a dependency when needs: is omitted, which would make the job run before the agent instead of after.

Ready-to-paste example

This mirrors the use case in the issue body (notify only when a push actually landed) and is what the requested post-agent-steps: would compile down to:

---
on:
  issue_comment:
    types: [created]

safe-outputs:
  push-to-pull-request-branch:
  add-comments:

jobs:
  post_agent:
    name: Post-agent notifications
    needs: [agent, safe_outputs]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Notify on successful push
        if: needs.safe_outputs.outputs.push_commit_sha != ''
        env:
          PUSH_SHA: ${{ needs.safe_outputs.outputs.push_commit_sha }}
          PUSH_URL: ${{ needs.safe_outputs.outputs.push_commit_url }}
        run: |
          echo "Agent pushed $PUSH_SHA → $PUSH_URL"
          # curl -X POST -d "sha=$PUSH_SHA" "$SLACK_WEBHOOK"

      - name: Re-request Copilot review when a PR was created
        if: needs.safe_outputs.outputs.created_pr_number != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR: ${{ needs.safe_outputs.outputs.created_pr_number }}
        run: |
          gh pr edit "$PR" --add-reviewer copilot-pull-request-reviewer

      - name: Alert on push failure
        if: fromJSON(needs.safe_outputs.outputs.code_push_failure_count || '0') > 0
        env:
          ERRORS: ${{ needs.safe_outputs.outputs.code_push_failure_errors }}
        run: |
          echo "::warning::Push failed: $ERRORS"
---

# My agentic workflow

... agent prompt ...

Outputs availability — verified against the compiler

From pkg/workflow/compiler_safe_outputs_job.go (function buildSafeOutputsHandlerOutputsAndActionSteps):

Full list of needs.safe_outputs.outputs.* and their gating conditions

Output	Declared when	Source line
process_safe_outputs_temporary_id_map	Always (when handler manager runs)	:271
process_safe_outputs_processed_count	Always	:272
create_discussion_errors	Always	:273
create_discussion_error_count	Always	:274
code_push_failure_errors	Always	:275
code_push_failure_count	Always	:276
assign_to_agent_assigned	safe-outputs.assign-to-agent set	:284
create_agent_session_session_number / _url	safe-outputs.create-agent-sessions set	:292-293
upload_artifact_count / _slot_N_tmp_id	safe-outputs.upload-artifact set	:304-307
sarif_file	safe-outputs.create-code-scanning-alerts set	:323
add_reviewer_reviewers_added	safe-outputs.add-reviewer set	:352
assign_milestone_milestone_assigned	safe-outputs.assign-milestone set	:357
assign_to_user_assigned	safe-outputs.assign-to-user set	:362
created_issue_number / _url	safe-outputs.create-issue set	:367-368
created_pr_number / _url	safe-outputs.create-pull-request set	:372-373
comment_id / _url	safe-outputs.add-comments set	:377-378
push_commit_sha / _url	safe-outputs.push-to-pull-request-branch set	:382-383
call_workflow_name / _payload	safe-outputs.call-workflow set	:387-388

A reference to an undeclared output evaluates to empty string, so the if: ... != '' guards above are safe to keep even when the matching safe-output isn't configured.

Behavior quirks worth knowing

1. needs: is mandatory for this pattern. pkg/workflow/compiler_jobs.go:513-865 auto-adds activation as a dependency when a custom job has no explicit needs:, which makes it run before the agent. Set needs: [agent, safe_outputs] to bypass that and run after.
2. Use if: always() on the job (and per-step guards) so it still fires when the agent or safe_outputs job fails — otherwise GitHub Actions skips it on upstream failure.
3. Fresh runner, no shared filesystem. Unlike post-steps: (which runs inside the agent job), jobs: runs in a new runner. Add actions/checkout@v6 if you need the repo; pass anything else through job outputs or artifacts.
4. Confirmed in compiled workflows. .github/workflows/workflow-skill-extractor.lock.yml:1176-1177 and .github/workflows/weekly-issue-summary.lock.yml:1184-1185 already reference ${{ needs.safe_outputs.outputs.create_discussion_errors }} from compiler-generated downstream jobs — proof the wiring works end-to-end.

Recommendations

• For the issue's stated use case (re-request Copilot review after a push lands), the jobs: workaround above is a complete solution and avoids the workflow_run clutter mentioned in the issue.
• A dedicated post-agent-steps: would still be a worthwhile DX improvement because it (a) hides the needs: / if: always() / fresh-runner boilerplate, (b) makes the intent obvious from the frontmatter, and (c) keeps parity with pre-agent-steps: / post-steps:. The compiler could lower it to exactly the job shown above.
• Consider documenting the jobs: + needs: [agent, safe_outputs] pattern as the interim recommendation in docs/src/content/docs/reference/steps-jobs.md alongside the existing outputs: section.

Key sources

• pkg/workflow/compiler_safe_outputs_job.go:271-389 — every safe_outputs output and its gating condition
• pkg/workflow/compiler_jobs.go:513-865 — custom jobs: compilation, including the activation auto-needs behavior
• docs/src/content/docs/reference/steps-jobs.md — public docs for jobs: and supported fields
• .github/workflows/workflow-skill-extractor.lock.yml:1176 — real compiled example consuming needs.safe_outputs.outputs.*
• Related: add-reviewer safe-output: ignores target-repo + does not use GraphQL botIds for Copilot bot #35283

Suggested next steps

1. Validate the example by saving it to a workflow file and running gh aw compile on it; confirm the generated post_agent job in the .lock.yml has needs: [agent, safe_outputs] and the expected ${{ needs.safe_outputs.outputs.* }} references.
2. If the team wants the sugar, scope post-agent-steps: as a schema addition in pkg/parser/schemas/main_workflow_schema.json that lowers to the same custom-job shape — implementation should be small.
3. Add a short section to steps-jobs.md showing the pattern so users discover it without grepping the source.

References: §26545520981

🔭 Intelligence gathered by Scout · opus47 5M · ◷