[plan] Implement on.needs API to allow pre_activation/activation to depend on custom credential-supply jobs #27748

Context

Reported in #27670. Even after fixing the YAML splicing bug (Bug 1) and needs: duplication bug (Bug 2), there is no way to make pre_activation or activation depend on a custom job that supplies credentials. This prevents sourcing on.github-app credentials (app-id, private-key) from an external secret manager via a custom job's outputs.

This is the symmetric counterpart to safe-outputs.needs shipped in #27472 — but on the on: / activation side.

Objective

Implement an on.needs frontmatter field (or equivalent) that allows users to declare one or more custom jobs as dependencies of pre_activation and activation, enabling $\{\{ needs.<job>.outputs.* }} expressions in on.github-app.app-id / private-key.

Approach

Preferred: on.needs: [<job>, ...] (parallel to safe-outputs.needs):

1. Schema: Add needs as an optional array field under the on: block in pkg/parser/schemas/.
2. Parser (pkg/parser/): Parse on.needs into the frontmatter config struct (pkg/workflow/frontmatter_types.go).
3. pre_activation compiler (pkg/workflow/compiler_pre_activation_job.go):
   • In buildPreActivationJob, emit the listed jobs as needs: for pre_activation.
   • Drop the assumption that pre_activation is always the structurally-first job when on.needs is non-empty.
4. activation compiler (pkg/workflow/compiler_activation_job_builder.go):
   • In configureActivationNeedsAndCondition, also add on.needs jobs to activation.needs (similar to how safe-outputs.needs jobs are added to safe_outputs.needs).
5. Expression validator: Validate that $\{\{ needs.<job>.outputs.* }} references in on.github-app.* resolve against on.needs (or already-accepted needs).
6. Documentation: Update relevant docs in docs/ to describe the new on.needs field.

Alternative: jobs.pre_activation.needs / jobs.activation.needs under jobs: — if the team prefers keeping dependency config next to the other per-job customisation from ADR-27138 rather than in on:.

Files to Modify

• pkg/parser/schemas/ — add needs to on: schema block
• pkg/workflow/frontmatter_types.go — add Needs field to On config struct
• pkg/workflow/compiler_pre_activation_job.go — wire on.needs into pre_activation.needs
• pkg/workflow/compiler_activation_job_builder.go — wire on.needs into activation.needs
• pkg/workflow/expression_extraction.go or expression validator — validate needs.* refs in on.github-app.*
• docs/ — document on.needs
• pkg/workflow/compiler_*_test.go — integration tests for the full spike scenario from the issue

Acceptance Criteria

• on.needs: [secrets_fetcher] compiles without error
• The compiled pre_activation job includes needs: [secrets_fetcher] in the output YAML
• The compiled activation job also includes secrets_fetcher in its needs:
• $\{\{ needs.secrets_fetcher.outputs.app_id }} in on.github-app.app-id passes expression validation
• The spike workflow from the issue (full external-secret-manager pattern) compiles cleanly and passes actionlint
• Documentation updated with on.needs field description and example
• make agent-finish passes (including make recompile)
  Related to on.github-app credentials cannot be sourced from a custom job's outputs (jobs.{pre_activation,activation}.pre-steps splicing/needs bugs + missing on.needs API) #27670

Generated by Plan Command for issue #27670 · ● 242.8K · ◷

• expires on Apr 24, 2026, 2:47 AM UTC