Support optional flag in depends_on for workflows and steps

[simonmeyerrr]

Fixes #6457
Fixes #3823

Summary

Extends depends_on to accept objects with name and optional fields, at both workflow and step level. When optional: true, the dependency is silently dropped if the referenced workflow/step is not part of the pipeline (e.g. filtered out by when conditions). If present, it is enforced as usual.

This is useful in monorepos where workflows use when: path or when: evaluate to only run when relevant files change, but a downstream workflow (like deploy) needs to wait for all checks that actually ran.

Example

# .woodpecker/deploy.yaml
depends_on:
  - check-a
  - name: check-b
    optional: true
  - name: check-c
    optional: true

steps:
  - name: deploy
    image: alpine
    commands:
      - echo deploying

If check-b and check-c are filtered out by their when conditions, deploy runs after check-a succeeds. If they are present, deploy waits for all three.

The same syntax works at step level within a workflow.

All existing formats (string, string[]) remain fully backward compatible.

Changes

• Add Dependency struct and DependsOn type (base/depends_on.go) with custom YAML marshal/unmarshal supporting string, string array, object array, and mixed array
• Use DependsOn type in both Workflow and Container (step) structs
• At build time, drop optional deps referencing non-existent workflows/steps (no runtime/queue changes needed)
• Update DAG compiler to handle optional step dependencies
• Update JSON schema, linter, and docs
• Add unit tests for the new type (unmarshal, marshal, helpers), DAG compiler (3 step-level cases), and step builder (4 workflow-level cases)
• Add e2e scenarios for both workflow-level and step-level optional dependencies

[6543]

I'm against a new top level field and would rather alter tje depends on in a unified way ... so steps also can use it etc...

[6543]

e.g. current depends_on allows string and strin array.
new could also allow object with name and mode field ...

-> need more consensus by all maintainers first

[6543]

looking at #3823 (comment) there is already consensus howbit should look like

[qwerty287]

Thanks! I also agree to @6543, would prefer a config like

depends_on: 
  - name: previous-step
    optional: true

And I think we should also support that on step level.

[simonmeyerrr]

Updated per feedback from @6543 and @qwerty287.

The separate optional_depends_on field is gone. Instead, depends_on now accepts objects alongside strings:

depends_on:
  - check-a
  - name: check-b
    optional: true

This works at both workflow level and step level, as suggested. Plain strings and string arrays still work as before.

Implementation follows the approach from #3823 (comment). The new DependsOn type lives in base/depends_on.go and is shared by both Workflow and Container. Optional deps are resolved early (build time for workflows, compile time for steps), so no runtime/queue changes were needed.

[woodpecker-bot]

Surge PR preview deployment was removed

[codecov]

Codecov Report

❌ Patch coverage is 92.36111% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 42.46%. Comparing base (b17515b) to head (3bf1aa9).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pipeline/frontend/yaml/constraint/depends_on.go	90.72%	7 Missing and 2 partials ⚠️
pipeline/frontend/yaml/linter/linter.go	71.42%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6461      +/-   ##
==========================================
+ Coverage   42.15%   42.46%   +0.31%     
==========================================
  Files         433      434       +1     
  Lines       28927    29044     +117     
==========================================
+ Hits        12193    12334     +141     
+ Misses      15630    15610      -20     
+ Partials     1104     1100       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 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.

outdated

[6543]

we should make this ready ... i wana have this in for next release

[6543]

I like how it is ... but this is breaking ... for workflow dag!!

before if dep was missing we where ignoring it .... it looks like

need to look into it more

looks like it is as before ...

[6543]

@qwerty287 I think it is ready ... but you as release manager should decide if we should merge it and release it now or in the next release ...

PS: on release docs pull need update ...

[qwerty287]

I'll check it tomorrow.