feat(workflow): support tags and labels selectors

[zack-is-cool]

what

• Enable --tags and --labels on atmos workflow, forwarding them to nested type: atmos steps alongside optional --stack.
• Preserve selector forwarding for parallel and matrix workflow controls.
• Document the feature, publish its changelog post, and add its workflow-roadmap milestone.

why

• Target existing workflows by component metadata without duplicating workflows or reconstructing their commands manually.

references

• Closes Allow --labels and --tags to be passed into atmos workflows the same way --stacks can be #2852

validation

• go test ./internal/exec -run TestExecuteWorkflow_ForwardsCommandLineFilters -count=1
• go test ./pkg/workflow -run 'TestAppendAtmosStepFlags|TestControlCommandExecutorExecuteAtmos' -count=1
• go test ./cmd/workflow -run TestWorkflowSelectorFlags -count=1
• git diff --check

Summary by CodeRabbit

• New Features

  • Added --tags and --labels selectors to workflow commands.
  • Selectors are forwarded to nested Atmos steps, including parallel and matrix workflows.
  • Selectors can be combined with --stack while preserving workflow ordering and execution behavior.

• Documentation

  • Updated CLI references with selector options and usage examples.
  • Added workflow selector guidance to the blog and roadmap.

[atmos-pro]

Tip

Atmos Pro  

No affected stacks workflow was detected for this pull request.
If this is expected, no action is needed.
Learn More. Ask AI.

[zack-is-cool]

CodeRabbit (@coderabbitai) full review pls

[coderabbitai]

@zack-is-cool Starting a full review of #2857.

✅ Action performed

Full review finished.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 03166ed2-ac7c-4839-af66-da00f939a093

📥 Commits

Reviewing files that changed from the base of the PR and between 10a66ed and 4ed1eb5.

📒 Files selected for processing (1)

• website/src/data/roadmap.js

🚧 Files skipped from review as they are similar to previous changes (1)

• website/src/data/roadmap.js

---

📝 Walkthrough

Walkthrough

The workflow command accepts --tags and --labels. These selectors pass through direct, parallel, and matrix workflow execution to nested type: atmos steps. Tests and documentation cover matching behavior and argument placement.

Changes

Workflow selector forwarding

Layer / File(s)	Summary
CLI filters and workflow initialization cmd/workflow/workflow.go, cmd/workflow/workflow_test.go, internal/exec/workflow.go, internal/exec/workflow_utils.go, internal/exec/workflow_no_stacks_test.go, internal/exec/workflow_test.go	Adds --tags and --labels, parses their values, and passes them into ExecuteWorkflow.
Nested Atmos selector forwarding internal/exec/workflow_control_adapter.go, internal/exec/workflow_utils.go, pkg/workflow/control_executor.go	Propagates selectors through direct, parallel, and matrix steps. AppendAtmosStepFlags inserts stack, tag, and label arguments before --.
Selector propagation tests internal/exec/workflow_utils_test.go, pkg/workflow/control_executor_test.go	Verifies selector forwarding, argument ordering, passthrough handling, and matrix execution counts.
Selector documentation agent-skills/skills/atmos-workflows/references/workflow-syntax.md, website/docs/cli/commands/workflow.mdx, website/blog/2026-08-03-workflow-tags-and-labels.mdx, website/src/data/roadmap.js	Documents selector flags, matching semantics, examples, and the shipped workflow milestone.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowCommand
  participant ExecuteWorkflow
  participant ControlCommandExecutor
  participant AtmosStep
  WorkflowCommand->>ExecuteWorkflow: Read --tags and --labels
  ExecuteWorkflow->>ControlCommandExecutor: Pass workflow command filters
  ControlCommandExecutor->>AtmosStep: Add stack, tags, and labels before --

Loading

Suggested reviewers: aknysh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies support for workflow tag and label selectors, which is the primary change.
Linked Issues check	✅ Passed	The changes implement --tags and --labels for atmos workflow and forward them to nested Atmos steps like --stack, including parallel and matrix controls.
Out of Scope Changes check	✅ Passed	The code, tests, documentation, blog post, and roadmap update all support the linked issue and stated workflow selector objectives.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@internal/exec/workflow_utils.go`:
- Around line 825-829: Update the command-display construction near
AppendAtmosStepFlags so displayCmd includes the effective commandFilters.tags
and commandFilters.labels selectors, matching the forwarded args alongside
finalStack. Prefer deriving displayCmd from the final args to keep displayed and
executed commands consistent.

In `@pkg/workflow/control_executor_test.go`:
- Around line 321-330: Add independent table cases to TestAppendAtmosStepFlags
for Tags-only and Labels-only inputs, verifying each selector is forwarded
without Stack or the other selector; include at least one of these cases with
the existing "--" argument and preserve the expected ordering.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ed1c4aba-88c5-444e-80db-ac6021e6275b

📥 Commits

Reviewing files that changed from the base of the PR and between ea46588 and 910693f.

📒 Files selected for processing (12)

• agent-skills/skills/atmos-workflows/references/workflow-syntax.md
• cmd/workflow/workflow.go
• cmd/workflow/workflow_test.go
• internal/exec/workflow.go
• internal/exec/workflow_control_adapter.go
• internal/exec/workflow_utils.go
• internal/exec/workflow_utils_test.go
• pkg/workflow/control_executor.go
• pkg/workflow/control_executor_test.go
• website/blog/2026-08-03-workflow-tags-and-labels.mdx
• website/docs/cli/commands/workflow.mdx
• website/src/data/roadmap.js

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.27%. Comparing base (e299b51) to head (4ed1eb5).

Files with missing lines	Patch %	Lines
internal/exec/workflow.go	50.00%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2857      +/-   ##
==========================================
+ Coverage   82.25%   82.27%   +0.01%     
==========================================
  Files        1810     1810              
  Lines      175701   175728      +27     
==========================================
+ Hits       144528   144572      +44     
+ Misses      23455    23434      -21     
- Partials     7718     7722       +4     

Flag	Coverage Δ
unittests	82.27% <90.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cmd/workflow/workflow.go	85.10% <100.00%> (+0.66%)	⬆️
internal/exec/workflow_control_adapter.go	100.00% <100.00%> (ø)
internal/exec/workflow_utils.go	75.92% <100.00%> (+0.13%)	⬆️
pkg/workflow/control_executor.go	97.90% <100.00%> (+0.14%)	⬆️
internal/exec/workflow.go	74.38% <50.00%> (-1.94%)	⬇️

... and 7 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[atmos-pro]

Tip

Atmos Pro  

No affected stacks workflow was detected for this pull request.
If this is expected, no action is needed.
Learn More. Ask AI.

[github-actions]

These changes were released in v1.225.0-rc.7.