Document behaviour for requeues for fanout behaviour in dags and steps.

[isubasinghe]

Pre-requisites

• I have double-checked my configuration
• I have tested with the :latest image tag (i.e. quay.io/argoproj/workflow-controller:latest) and can confirm the issue still exists on :latest. If not, I have explained why, in detail, in my description below.
• I have searched existing issues and could not find a match for this bug
• I'd like to contribute the fix myself (see contributing guide)

What happened? What did you expect to happen?

See this PR: #15736

steps.template.id should always be something when referred to, but this is impossible for steps with fan out behaviour.

At least document this impossibility.

Version(s)

:latest

Paste a minimal workflow that reproduces the issue. We must be able to run the workflow; don't enter a workflow that uses private images.

N/A

Logs from the workflow controller

N/A

Logs from in your workflow's wait container

N/A

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• DAG and Steps workflows stuck in Running when referencing expanded task/step node properties (e.g. {{tasks.X.id}}, {{steps.X.id}}) #15737

🔗 Related PRs

#15144 - fix: type-aware application of template defaults (#14899) [merged]
#15240 - fix: use input.defaults for suspend templates [merged]
#15442 - fix: requeue workflow if expected variables are missing. Fixes #15513 [merged]
#15736 - fix: add stepgroup and taskgroup to scope. Fixes #15737 [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Add a focused section to docs/variables.md explaining StepGroup/TaskGroup behavior for fanout scenarios, since this is where all variable documentation is centralized
• Explain that node-level variables (.id, .status, etc.) resolve to the group node, not individual iterations
• Add a brief cross-reference in the loops walkthrough to connect the two documentation areas
• Keep changes minimal and aligned with existing documentation style and structure

Implementation Steps

Document Fanout Variable Behavior

This phase adds clear documentation explaining how node-level variables behave when referencing steps or tasks that use fanout expansion, addressing the knowledge gap identified in PR #15736.

Task 1: Update Variables Documentation with Fanout Behavior Section

Add a dedicated subsection to docs/variables.md that explains the behavior of node-level variables when referencing fanned-out steps or tasks.

• Add a new subsection titled "Referencing Fanout Steps and Tasks" (or similar) after the existing Steps Templates and DAG Templates tables in docs/variables.md
• Document that when a step/task uses withItems, withParam, or withSequence, the workflow controller creates a virtual "StepGroup" or "TaskGroup" node that acts as a parent to the individual expanded iterations
• Explain that variables like steps.<STEPNAME>.id, tasks.<TASKNAME>.id, .status, .startedAt, .finishedAt, etc. resolve to the group node's values, not any individual expanded child node
• Clarify that individual expanded iterations (e.g., fanout(0:a), fanout(1:b)) are not directly addressable via template variables
• Reference the existing documentation that .outputs.parameters and .outputs.parameters.<NAME> aggregate into JSON arrays for fanout scenarios (this is already documented, just cross-reference it for completeness)
• Optionally include a brief note about the requeue mechanism: if a downstream step/task references these variables before the fanout completes, the workflow controller will requeue until the values are available

Task 2: Add Clarifying Note to Loops Documentation

Add a brief note in docs/walk-through/loops.md pointing users to the variables documentation for information about referencing fanout steps from downstream steps.

• In docs/walk-through/loops.md, add a short paragraph or note near the end of the relevant section (after explaining withItems/withParam/withSequence mechanics)
• Direct readers to docs/variables.md for details on how downstream steps/tasks can reference outputs and metadata from fanned-out steps
• Keep this addition minimal—just a cross-reference to avoid duplicating documentation

🤖 Prompt for AI agents

This phase adds documentation to explain how node-level variables behave when
referencing fanned-out steps or tasks that use `withItems`, `withParam`, or
`withSequence`. The goal is to fill a documentation gap where users may be
confused about which node ID is resolved in fanout scenarios.

**Task 1: Update `docs/variables.md`**
- After the existing Steps Templates and DAG Templates variable tables, add a
new subsection titled "Referencing Fanout Steps and Tasks" (or similar)
- In this subsection:
- Explain that when a step/task uses `withItems`, `withParam`, or
`withSequence`, the workflow controller creates a virtual "StepGroup" or
"TaskGroup" node as a parent to all individual expanded iterations
- Document that variables such as `steps.<STEPNAME>.id`, `tasks.<TASKNAME>.id`,
`.status`, `.startedAt`, `.finishedAt`, etc. resolve to the **group node's**
values, not any individual expanded child node
- Clarify that individual expanded iterations (e.g., `fanout(0:a)`,
`fanout(1:b)`) are not directly addressable via template variables
- Cross-reference the already-documented behavior that `.outputs.parameters` and
`.outputs.parameters.<NAME>` aggregate into JSON arrays for fanout scenarios
- Optionally include a brief note about the requeue mechanism: if a downstream
step/task references these variables before the fanout completes, the workflow
controller will requeue until the values are available

**Task 2: Update `docs/walk-through/loops.md`**
- Near the end of the relevant section (after explaining
`withItems`/`withParam`/`withSequence` mechanics), add a short paragraph or note
- Direct readers to `docs/variables.md` for details on how downstream
steps/tasks can reference outputs and metadata from fanned-out steps
- Keep this addition minimal — just a cross-reference, no duplication of
documentation

Research

The Argo Workflows documentation is organized under the docs/ directory. Variable substitution behavior is primarily documented in docs/variables.md, which contains tables describing available variables for different template types (Steps, DAG, Loops). The file already documents that output parameters become JSON arrays when fanout is used, but does not explain the behavior of node-level variables (.id, .status, etc.) in fanout scenarios. The loops walkthrough in docs/walk-through/loops.md covers the mechanics of withItems/withParam/withSequence but focuses on the {{item}} variable usage rather than downstream reference behavior.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase adds documentation to explain how node-level variables behave when
referencing fanned-out steps or tasks that use `withItems`, `withParam`, or
`withSequence`. The goal is to fill a documentation gap where users may be
confused about which node ID is resolved in fanout scenarios.

**Task 1: Update `docs/variables.md`**
- After the existing Steps Templates and DAG Templates variable tables, add a
new subsection titled "Referencing Fanout Steps and Tasks" (or similar)
- In this subsection:
- Explain that when a step/task uses `withItems`, `withParam`, or
`withSequence`, the workflow controller creates a virtual "StepGroup" or
"TaskGroup" node as a parent to all individual expanded iterations
- Document that variables such as `steps.<STEPNAME>.id`, `tasks.<TASKNAME>.id`,
`.status`, `.startedAt`, `.finishedAt`, etc. resolve to the **group node's**
values, not any individual expanded child node
- Clarify that individual expanded iterations (e.g., `fanout(0:a)`,
`fanout(1:b)`) are not directly addressable via template variables
- Cross-reference the already-documented behavior that `.outputs.parameters` and
`.outputs.parameters.<NAME>` aggregate into JSON arrays for fanout scenarios
- Optionally include a brief note about the requeue mechanism: if a downstream
step/task references these variables before the fanout completes, the workflow
controller will requeue until the values are available

**Task 2: Update `docs/walk-through/loops.md`**
- Near the end of the relevant section (after explaining
`withItems`/`withParam`/`withSequence` mechanics), add a short paragraph or note
- Direct readers to `docs/variables.md` for details on how downstream
steps/tasks can reference outputs and metadata from fanned-out steps
- Keep this addition minimal — just a cross-reference, no duplication of
documentation

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!