Feature: agent-job-level if:/ eeds: hook to gate the agent on a custom setup job

[Evangelink]

Summary

Provide a first-class way to make the agent job depend on (and be conditionally skipped by) a user-defined custom job declared in the workflow frontmatter — equivalent to an agent.needs: / agent.if: knob.

Motivation

Today the only ways to gate the AI agent on the outcome of work that must happen before the agent runs are:

1. Put all the setup logic inline in steps:/pre-agent-steps: and accept that the agent boots even when the setup signals "nothing to do" (wastes Copilot/AI budget, spams report-failure-as-issue).
2. Reach into the compiled *.lock.yml and add a custom job + wire needs: / if: onto the agent job by hand — which we obviously can't do because gh-aw owns that file.
3. Use the pre_activation.needs: trick + a top-level if: on the workflow to cascade-skip activation → agent. This works but is non-obvious, undocumented, and breaks down the moment you also want the agent to see the upstream job's outputs cleanly.

We hit this concretely on a build-failure-analysis workflow that should only invoke an AI agent when the build is red. To get there we ended up with a ~100-line custom build: job in the workflow source, plus this pattern in the frontmatter:

on:
  needs: [build]   # pre_activation / activation now wait for `build`

if: needs.build.outputs.outcome == 'failure'   # cascades to activation → agent skipped

That works, but:

• on.needs: cascading into activation is undocumented and surprising (and reportedly was the cause of Bug: on.needs directive leaks into emitted on: block (invalid Actions YAML) #35943).
• Top-level if: is repurposed to mean "skip the agent" — there is no real "agent-job-level if:".
• New contributors can't figure this out from the docs.

Workaround reference: microsoft/testfx#8738 — "Skip build-failure-analysis agent on green builds".

Proposed solution

Add explicit frontmatter:

jobs:
  build: { ... custom job ... }

agent:
  needs: [build]
  if: needs.build.outputs.outcome == 'failure'

…that compiles to needs: and if: directly on the generated agent job, with needs.build.outputs.* resolvable in the agent prompt's env injection. This eliminates the pre_activation.needs + top-level-if: cascade trick.

Related

• ASI-08: Add circuit breaker for repeatedly failing workflows #28776 (circuit breaker) — adjacent but different: that issue is about repeated failures, not about gating a single run on a custom signal.
• Feature request: post-agent-steps section that runs after the safe_outputs job #35284 (closed, post-agent-steps) — solves the after-agent side; this is the before-agent side.
• Bug: on.needs directive leaks into emitted on: block (invalid Actions YAML) #35943 — on.needs leaking into emitted on: block; the workaround above relies on a related (still surprising) behavior.

Environment

• gh-aw: v0.75.x

[pelikhan]

/scout investigate "needs" frontmatter element

[github-actions]

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

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan — investigate the needs frontmatter element

Executive Summary

needs already exists in gh-aw frontmatter at three distinct levels, but none of them is the agent.needs: / agent.if: knob this issue (#38564) asks for. The closest existing mechanism — on.needs: (ADR-27895) — was designed for credential supply before activation, not for gating the agent on a setup job's outcome. The cascade-skip trick the issue describes works only because of a GitHub Actions quirk (a skipped needs job skips its dependents), which is exactly the lever a proper agent.if: would formalize.

Click to expand detailed findings

Research Findings

1. Where needs lives today in gh-aw frontmatter

Level	Frontmatter	Meaning	Compiled to
on.needs:	under on:	jobs that pre_activation + activation must wait for	needs: on both pre_activation and activation
custom job needs:	inside jobs.<id>.needs	standard GHA job-to-job deps	passed through verbatim
implicit needs: activation	(none — auto-added)	custom jobs run after the activation gate by default	auto-injected unless excluded

Key source files: pkg/workflow/on_needs_validation.go, compiler_pre_activation_job.go (extractOnNeeds, L788), compiler_activation_job_builder.go (configureActivationNeedsAndCondition, L656-704), compiler_jobs.go (buildCustomJobs, L513-722), compiler_main_job.go (agent-job wiring, L101-150).

2. on.needs: design intent (ADR-27895)

The ADR is explicit: on.needs exists so on.github-app expressions like ${{ needs.secrets_fetcher.outputs.app_id }} resolve before activation mints a token. Jobs in on.needs are exempted from the automatic needs: activation guard — i.e. they run before the gate. The ADR even flags the negative consequence: "this widens the surface of pre-activation execution... must be considered when auditing workflow security." So on.needs is the wrong tool for build-failure gating: it makes the setup job run pre-activation (before permission/skip checks), not as a normal gate on the agent.

3. The agent job's needs:/if: are compiler-owned, not user-settable

In compiler_main_job.go:

• The agent job auto-needs: activation when an activation job exists (L101-104).
• The agent job's if: is cleared when activation exists, because activation handles pre-checks (L56-67).
• Custom jobs become agent dependencies only if they don't depend on pre_activation/agent and are referenced in the markdown body / outputs (L110-150).

This is precisely why the issue author cannot set an agent-level if: today — there is no surface for it, and the compiler actively clears the slot.

4. Why the cascade trick in the issue works (GitHub Actions semantics)

Confirmed via GHA community reports (community discussions #26945, #45058; actions/runner #2205): when a job listed in another job's needs is skipped, the dependent job is skipped too by default, and success() returns false if any upstream is skipped. The issue's on:\n needs: [build] + top-level if: needs.build.outputs.outcome == 'failure' works by letting that skip cascade pre_activation → activation → agent. It is load-bearing on an unintuitive GHA behavior — which matches the issue's complaint that it's "non-obvious and undocumented," and ties to #35943 (on.needs leaking into the emitted on: block).

5. Gap analysis for the proposed agent.needs: / agent.if:

• A real agent.if: is cleaner than the cascade trick: it sets if: directly on the agent job, and GHA's skip-cascade naturally skips the agent's downstream jobs (detection, conclusion, safe-output jobs) — but those downstream jobs must tolerate a skipped agent (many gh-aw post-jobs already use if: always() / !cancelled() guards; these need an audit, see discussions #26945 on always() itself being skipped under a skipped need).
• needs.<job>.outputs.* resolution in the agent prompt's env injection already has precedent: compiler_main_job.go L129-150 adds custom jobs referenced in markdown as direct agent deps. So output plumbing is partially solved.
• The proposal should not reuse on.needs semantics (pre-activation), since the build job should run after permission/skip gating, not before.

Recommendations

1. Treat agent.needs:/agent.if: as a new, distinct surface — not an extension of on.needs:. The intent is post-activation gating, whereas on.needs: is pre-activation credential supply.
2. Set if: directly on the generated agent job (the slot currently cleared at compiler_main_job.go L56-67) and add the named jobs to the agent's needs:. Let GHA's skip-cascade handle downstream skipping rather than reusing the top-level-if: cascade.
3. Audit gh-aw's post-agent jobs (conclusion, detection, safe-output processing) for correct behavior when agent is skipped (not failed/cancelled) — the GHA always()-under-skipped-need quirk is the main footgun.
4. Document the distinction between on.needs: (pre-activation), custom-job needs: (job graph), and the new agent.needs:/agent.if: (agent gating) in reference/triggers.md and reference/steps-jobs.md, since conflating them is exactly what bites new contributors today.
5. Cross-reference Bug: on.needs directive leaks into emitted on: block (invalid Actions YAML) #35943 when implementing — the existing on.needs cascade leak should not be replicated in the new knob.

Key Sources

• ADR-27895 on.needs design — docs/adr/27895-on-needs-explicit-pre-activation-job-dependencies.md (in-repo)
• on.needs: docs — docs/src/content/docs/reference/triggers.md (L701+)
• Custom jobs docs — docs/src/content/docs/reference/steps-jobs.md (L53-173)
• Agent-job wiring — pkg/workflow/compiler_main_job.go (L56-150)
• GHA skip-cascade behavior — community #26945, community #45058, actions/runner #2205

Suggested Next Steps

1. Decide whether agent.if: should also skip downstream safe-output jobs (likely yes) and verify each post-job's if: guard handles a skipped agent.
2. Prototype emitting needs:/if: on the agent job behind the new frontmatter, with one integration test mirroring on_needs_integration_test.go.
3. Add a validation pass (like on_needs_validation.go) ensuring agent.needs: references only declared custom jobs and not built-in control jobs.

🔭 Intelligence gathered by Scout · ◷