Skip a plugin step (show it as “skipped”) based on a result computed in an earlier step

[zivklein21]

I have an Nx monorepo with several frontend apps under clients/ and shared code under clients/libs/. I use a matrix workflow with one entry per app. Each entry builds and pushes a Docker image with the docker-buildx plugin.

A change in clients/libs/ should rebuild only the apps that depend on that lib. Which apps those are is dynamic. The only reliable way to know is to run nx show projects --affected inside the pipeline. Path filters can’t express it, because the dependencies change over time.

So every matrix entry starts. The first step runs Nx and decides whether this app is affected. If it isn’t, I want the later steps, especially the docker-buildx plugin step, to be skipped (grey), while the workflow stays green.

Simplified workflow

matrix:
  include:
    - NAME: app-a
    - NAME: app-b

when:
  - event: push
    path:
      include:
        - clients/${NAME}/**
        - clients/libs/**

steps:
  check-affected:
    image: node:22
    commands:
      - cd clients && pnpm install --frozen-lockfile
      - npx nx show projects --affected --base=${CI_PREV_COMMIT_SHA} --type app > ../affected.txt
      - grep -qx "${NAME}" ../affected.txt || touch ../.skip   # not affected

  buildx:                 # should be skipped when .skip exists
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: my-repo/${NAME}
      dockerfile: clients/${NAME}/Dockerfile
    depends_on: [check-affected]

What I tried

• exit 1 in check-affected: the following steps don’t run, but the workflow and pipeline turn red.
• exit 1 with failure: ignore: the workflow stays green, but the next steps still run.
• when: status: success / failure on the next step: this looks at the workflow status, not at a specific step’s result.
• when: evaluate checking an env var or a file: evaluate is resolved before the pipeline starts, so it can’t see anything an earlier step produced.
• Exit code 78 (as in Drone): as far as I can tell, Woodpecker doesn’t support it.
• Current workaround: the first step writes an .env file that the buildx plugin reads with env_file, pointing it to an empty FROM scratch Dockerfile with dry_run: true. It works, but the step still runs and shows green, and it’s a hack.

Questions

1. Is there a supported way for one step to make a later step skipped at runtime? For example, a special exit code, a step output, or a condition based on a previous step’s result, such as when: step.check-affected.outcome.
2. If not, is there an open issue or a planned feature for this, similar to GitHub Actions’ steps.<id>.outcome or Drone’s exit code 78?
3. For dynamic monorepo builds like this one, what does the Woodpecker team recommend: a config extension service that generates the matrix, triggering pipelines through the API, or something else?

Thanks!

[6543]

@zivklein21 i guess you need var eskaping: https://woodpecker-ci.org/docs/usage/environment

there is a distinct difference between runtime and compile time variables

[6543]

(still the step itslefe will show sucess state ... but you can skip in runtime by exit 0 early ...)

[GLec1er]

A successful no-op does not mark the later step as skipped. The runtime's skip check uses pipeline error state and success/failure flags; exit-code handling treats nonzero codes as errors, without a special case for 78. A marker file and exit 0 do not add a skip condition to another step.

A configuration extension can generate the affected builds before agent steps run. It would need to compute Nx's affected projects itself, with the correct base/head commits and dependencies. It cannot consume affected.txt from the pipeline it is still generating.

Generate only the affected app builds if that meets the goal. Omitted builds will be absent from the graph, though—not grey skipped entries. If retaining every entry with runtime skip status is essential, this does not satisfy it.

A planner that triggers child pipelines is another option, with separate pipeline results and authorization to manage. I have checked the runtime/extension contract, not run your Nx repository, and do not have a confirmed roadmap reference for runtime conditionals.

[6543]

you could also make a pipeline that first evaluates what to trigger and uses the trigger plugin and sets env var in the way to only trigger wanted workflow permutations etc...

.. only downside is that you will get two pipelines not directly linked to each other ...

[zivklein21]

To make the case concrete: I run one workflow with a matrix over services. The first step of each permutation decides whether that service actually needs to run (e.g. based on changed paths). With a matrix I get exactly the UI I want: one pipeline, one row per service, clearly showing which ones ran and which were skipped.

I did try the trigger-plugin approach, and it was a worse fit for this:

• the work is split into separate pipelines that aren't linked to each other in the UI
• it runs more builds, without a clear indication of which service is running right now
• the overview I get from the matrix is lost

So what I'm looking for is a way for a step to say "stop here, mark the rest as skipped, not failed", inside the same workflow.

To address the magic-number concern, the behaviour could be explicit and opt-in instead of a hardcoded 78. For example, per step:

steps:
  - name: check
    image: alpine
    commands:
      - ./should-run.sh
    skip_on_exit_code: 78   # or a list

Nothing changes unless someone configures it. Users coming from Drone can use 78, and anyone else can pick a code that fits their scripts.

Would something along these lines be acceptable? If so, I'm happy to rework the PR to match whatever shape you prefer.

[6543]

... I like the idea of having a way to make backchannel comunication easy but the current approach is not generic enouth ... as we might wana signal more stuff ...

steps:
  - name: check
    image: alpine
    commands:
      - ./should-run.sh
    signals:
      skip: 78

through what else do we wana signal ... (restart?, kill, skip, pause, ...?). but a single signal kan only do so much ...

... I alrady expored #2953 but It never got in a state I fully support and nor did others work on it jet
... and actually your feature request is quite old: #294 but back then the codebase was not in a good shape we are today ...

[6543]

PS: in the old issue a callback api was also the one we leaned towards ... #2954

[zivklein21]

What I do today

In my setup the first step of each matrix entry checks whether the app is affected. When it isn't, the step exits with code 1, so the following steps (build, image push, Helm update) don't run. This prevents the unnecessary build, but it marks the workflow and the whole pipeline as failed, even though nothing went wrong. As a result:

• Almost every pipeline is red, since most pushes affect only one or two apps.
• A real failure looks exactly like a "not affected" entry, so I have to open each log to tell them apart.
• Failure notifications fire for entries that were simply not needed.

The pipeline behaves the way I want, but the status it shows is wrong. With this change the same step exits with 78 instead, and the status reflects what actually happened: the check is green, the skipped steps are grey, and the workflow is green.

[zivklein21]

@6543
Hi, can we continue discussing on this issue, we really need this feature for our flow…

[6543]

If you need this feature right NOW i would argue a fork is a good way to get that ... woodpecker should be stright forward to build ... if you need help and it does not work out of the box just ask.

as for continue discussion, this here is the best way to go ... I just want to say that here almost all work is done in free time voluntarily, so dont expect ETAs etc...

that said I like the idea of having a way to make backchannel comunication easy but the current approach is not generic enouth ... as we might wana signal more stuff.

[zivklein21]

At our end, the tool is managed centrally, so updating versions requires an official release since it impacts multiple teams.

Can we brainstorm together on how to implement this in a generic way? And if a generic approach isn't feasible right now, why does this capability exist in Drone while it's absent here, given that Woodpecker is originally based on Drone?

[6543]

well it is based on a realy early drone version (0.8) but a lot of code itterations, fixing, extending, adding features, revision config vormat ... have passed ... so you can not expect to have a 1:1 replacement at all ...

[6543]

still could you point me at drone docs ... It's always a good idea to see how others did at least aproach it from the user experience side ... still that does not mean we have to copy it

[GLec1er]

@6543 The reference is Brad Rydzewski's Drone FAQ: “How to exit a Pipeline early without Failing”, from March 2019. It describes exit 78 keeping the pipeline successful, skipping pending steps and letting already-running steps finish.

The corresponding historical runner code calls state.SkipAll() after receiving 78.

For the proposed skip signal, useful acceptance cases would cover pending steps, already-running siblings and isolation between matrix workflows. Cleanup/notification steps need an explicit policy too—the open question in #7418 is relevant there. That would make the intended behavior clear independently of the chosen exit-code syntax.

[zivklein21]

Makes total sense. I completely agree that we need clear acceptance criteria covering pending steps, running siblings, matrix isolation, and cleanup policies (I'll check out #7418 for that).

If I draft a comprehensive proposal outlining these exact behaviors and a clean implementation approach, would you be open to reviewing a PR for it?

[GLec1er]

Yes, I can help review a written proposal and its regression tests. API approval, merging and release timing would still need the maintainers.

I looked at the current #7418 diff: skipRemaining is checked before the normal success/failure conditions. Please make the cleanup/notification policy explicit in the proposal.

I would also want tests showing that an earlier error—or a failure from a sibling already running when skip arrives—still fails the workflow, and that skipping one matrix workflow leaves the others unaffected. Keeping the behavior proposal and tests linked from #7418 would make that review concrete.

[zivklein21]

If I manage to implement this signals part in a generic way in my fork, do you think it's realistic that it would be reviewed, approved, and merged into an upcoming release?

[zivklein21]

Thanks for the feedback, both of you. I reworked the idea into a generic mechanism instead of a hardcoded exit code 78, following the signals: shape @6543 sketched above. Here is what I built, how it behaves, and what I tested. Happy to change names or shape, and to split it into smaller PRs.

Summary

A step can map its own exit codes to signals. When the step exits with a mapped code, the runtime performs the signal's action instead of failing the step. Nothing changes for steps without signals:: exit 78 is still a normal failure.

steps:
  check-affected:
    image: node
    commands:
      - npx nx show projects --affected --type app | grep -qx "${APP}" || exit 78
    signals:
      skip: 78

Five signals are implemented:

Signal	Step shown as	Effect
skip	success	Steps that would run after it are skipped, the workflow stays green
success	success	Nothing else, the workflow continues (e.g. a linter that exits 1 on warnings)
restart	(runs again)	Runs the step again, up to max_restarts times (default 2)
cancel	success	Stops this workflow (running steps too), the workflow is shown as killed
pause	success	Pauses the workflow until a user clicks Resume or Decline, or a timeout fires

Config shape

Short form, one code or a list:

signals:
  skip: 78
  success: [1, 2]
  restart: 75
  cancel: 70
  pause: 71

Long form, for signals with options:

signals:
  restart:
    exit_codes: [75, 76]
    max_restarts: 5        # 1-10, default 2
  pause:
    exit_codes: 71
    timeout: 30m           # optional, no decision within 30m ...
    on_timeout: resume     # ... resume, or decline (default)

Validation (compiler and linter): known signal names only, exit codes 1–255, an exit code may be mapped to only one signal per step, max_restarts 1–10 and only on restart, timeout (a positive duration) and on_timeout (decline / resume) only on pause. The linter warns about 126, 127 and ≥128 (shell and kill-signal codes, e.g. 137 for OOM). An OOM-killed step always fails, even if 137 is mapped.

How it works

• Generic by design: the compiler turns signals: into an exit code → signal map on the backend step. The runtime looks up the exit code and runs a handler from a signal → handler table. A new signal is one constant plus one handler. If the callback API from Draft: Agent pipeline callback api #2953 / Callback Endpoint for workflow environments #2954 lands later, it can send the same named signals; only the trigger changes.

• Stage boundaries: skip and pause take effect once the current stage has finished, the same way failures are applied today (r.err is set after the stage). Parallel siblings always run to the end, whatever the goroutine timing.

• restart re-runs the container in the agent with the same workspace. A marker line in the log separates the attempts (--- woodpecker: step sent restart signal, starting attempt 2 of 3 ---), and line numbers keep counting across attempts. Detached steps and services are not restarted; the linter warns about it.

• cancel stays in the agent: the runtime cancels its own context, and the existing "agent reports the workflow as canceled" path marks it killed. Other workflows are not affected.

• pause is the only signal that needs the server:

  • a new gRPC call Pause(workflow_id, step_uuid, deadline, resume_on_timeout) → (resume, timed_out) (proto version 16 → 17)
  • a new workflow status paused. The pipeline itself stays running, so forge statuses and badges don't change.
  • two endpoints, POST .../pipelines/{n}/workflows/{id}/resume and .../decline, with the same permission as pipeline approval (push)
  • Resume / Decline buttons on the paused workflow in the UI

  The decision is kept until the agent picks it up, so an agent that reconnects still gets it. Cancelling the pipeline also cancels paused workflows. If the pausing step is in the last stage, there's nothing to wait for and the workflow doesn't pause.

  With timeout, the agent sends an absolute deadline in the Pause call, so a reconnect doesn't restart the clock. The server applies on_timeout: resume sets the workflow running again (an automatic approval, e.g. "continue unless somebody vetoes"), decline stops it as killed. The log of the pausing step shows how long the workflow waits and what happened.

Acceptance cases from @GLec1er

Case	Behaviour
Pending steps	Skipped (shown grey)
Siblings already running when skip arrives	Run to the end; a failure still fails the workflow
Earlier error	The workflow stays failed, skip never clears the error
Matrix isolation	Each matrix entry is its own workflow and runtime; skip, cancel or pause in one entry doesn't touch the others
Cleanup / notification steps (when: status: [success, failure])	Skipped too, like Drone's SkipAll(). The skip means "nothing to do here", and the workflow is green anyway. I can switch to "still run them" if you prefer, it's a one-line change in shouldSkipStep.

Each case has a runtime test (see below).

What I tested

• Unit and integration tests:
  • YAML parsing (both forms), compiler validation, linter and JSON schema
  • runtime: every signal; parallel siblings; earlier errors; matrix isolation; restart limits and max_restarts; cancel stopping running siblings; pause resume, decline, timeout, cancel while paused and errors
  • server: pause registry (reconnect, decision before the agent waits, server restart, double decision), gRPC Pause handler (timeout with resume and with decline, deadline already passed, reconnect after a decision, wrong org, finished workflow, step of another pipeline), paused status merging
  • agent: log line numbers continue across restarts
• go test -tags test ./... passes. The runtime tests pass repeatedly with -race. Web: vue-tsc, eslint, prettier and vitest pass.
• woodpecker-cli exec with ~40 workflows, including matrix workflows, checked against the expected result of each case.
• A local server and agent (Docker backend, GitHub forge) built from the branch, for skip, restart and pause with Resume and Decline. Screenshots below. The pause timeout is covered by unit and integration tests so far; I'll add a note once I've checked it on the instance too.

Screenshots from a local instance

skip in a matrix: one entry per app. app-a is affected and builds. For app-b, check-affected exits 78: it stays green, build and push are skipped (grey), and the workflow is green.

restart with max_restarts: 5: the step exits 76 three times and passes on attempt 4. A marker line separates the attempts and the line numbers keep counting. The steps that never pass (restart-default, restart-max-1) fail after their last attempt, so the workflow is red on purpose.

pause: approve exits 71 and is green. The workflow pauses after the parallel slow-tests step has finished, and shows Resume / Decline buttons. After Resume, deploy ran and the workflow finished green. In the other matrix entry, Decline stopped the workflow without running deploy.

Open questions

1. Is signals: with these names and the short/long form the shape you want?
2. Should cleanup steps (status: [success, failure]) run or be skipped after skip?
3. The PR is fairly large. Would you prefer:
   • (a) skip / success / restart / cancel first (runtime and config only, no protocol change), then pause (protocol, API, UI) as a follow-up, or
   • (b) one PR?
4. For pause: is a new paused workflow status OK, or would you rather reuse something existing?
5. For pause with timeout: should the UI show the remaining time? That needs the deadline stored on the workflow, so it means a DB migration. Today it's only visible in the step log.

I'll open the PR as a draft and link it here.

[GLec1er]

I'd review the exit-code mapping and runtime signals separately from pause. That gives the signals: syntax a concrete use case in the first PR. pause can then get its own review for the protocol, workflow state, permissions and UI.

For skip, I'd keep the skip-all behavior if that's the intended contract, and document what happens when a running sibling fails. The workflow can still fail while a pending failure notification or cleanup step gets skipped, because skipRemaining takes precedence over the status flags. I'd make any cleanup exception explicit rather than infer it from when.status.

One change to the Nx example before it goes into the docs. nx ... | grep ... || exit 78 can turn an Nx error into a green skip. I reproduced that with a shell stub returning 2. Check Nx's exit status first (for example, affected=$(npx nx show projects --affected --type app) || exit 1), then match the captured output with grep -Fxq. Emit 78 only for grep's no-match status (1), and fail normally on other errors.

[zivklein21]

PR: #7478

Thanks, I've applied all three points.

I split the work as you suggested. The first PR has the signals: syntax with skip, success, restart and cancel. These only touch the config and the runtime, so there's no protocol, workflow state, API or UI change. pause will follow in its own PR.

For skip, I kept the skip-all behavior as the intended contract and documented the sibling case. A running sibling still finishes, and if it fails, the workflow fails. A pending status: [failure] step is still skipped in that case, because the skip takes precedence over the status flags. The docs warn against relying on failure notifications or cleanup steps after a step that can send skip, and TestSkipSignalSkipsFailureStepAfterSiblingFailed covers it. I didn't add a cleanup exception. If one is needed later, it would be an explicit option rather than inferred from when.status.

Thanks for catching the Nx example too. It's only a docs example, and it now checks Nx's exit status first and emits 78 only for grep's no-match status, so an Nx error fails the step.

[cookielevanna5]

Would like this feature in the next release
we also work with an Nx-based monorepo and woodpecker - this could be extremely helpful for us too