> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run one workflow when another finishes or fails

> Chain Reliant workflows with a workflow_event trigger: start a follow-up run whenever another workflow's run fails, finishes or waits for a person.

A nightly job that fails at 3am helps nobody until someone notices. In this guide a second workflow starts by itself every time the first one's run fails, and receives which run failed and why. Neither workflow names the other in its graph: the follow-up declares a `workflow_event` trigger, and you turn it on. [Workflow events](https://docs.reliantlabs.io/automations/workflow-events.md) lists every field and payload key.

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)).
* A Reliant project for the repository and a connected machine that holds it ([Run a machine from the terminal](https://docs.reliantlabs.io/cli/run-a-machine.md)).
* The workflow you want to follow up on, in `.reliant/workflows/`. This guide uses a stand-in called `nightly-check`.

**1. Know when a run counts as failed**

A run reports `failed` when it errors, or when it ends at a node that declares `outcome: failure`. This stand-in runs a check and routes a non-zero exit to such a node:

```yaml .reliant/workflows/nightly-check.yaml theme={null}
name: nightly-check
description: Runs the project's checks and ends failed when they fail.

entry: [check]

nodes:
  - id: check
    type: run
    args:
      command: "echo 'FAIL: 2 tests failed'; exit 1"
    timeout: 5m

  - id: passed
    type: save_message
    outcome: success
    args:
      role: assistant
      content: "Checks pass."

  - id: failed
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: "Checks failed: {{nodes.check.stdout}}"

edges:
  - from: check
    cases:
      - to: passed
        condition: nodes.check.exit_code == 0
    default: failed
```

A run whose `run` node exits non-zero but reaches no failure node counts as `finished`: the exit code is an output to route on.

**2. Declare the follow-up**

The trigger watches `nightly-check` for `failed` and maps fields of the event into the follow-up's inputs:

```yaml .reliant/workflows/failure-follow-up.yaml theme={null}
name: failure-follow-up
description: Opens a follow-up run for every failed nightly-check run.

# lint:allow no-failure-path — its only step writes a message into this run
triggers:
  - name: nightly-check-failed
    workflow_event:
      workflows: [nightly-check]
      outcomes: [failed]
    inputs:
      failed_run: "{{ trigger.payload.run_id }}"
      reason: "{{ trigger.payload.error }}"

inputs:
  failed_run:
    type: string
    default: ""
  reason:
    type: string
    default: ""

entry: [note]

nodes:
  - id: note
    type: save_message
    outcome: success
    args:
      role: assistant
      display_style: warning
      content: |
        nightly-check run {{ inputs.failed_run }} failed.
        {{ inputs.reason }}
```

Add `finished` or `blocked` to `outcomes` to react to those too. To have an agent investigate instead, replace `note` with an agent node:

```yaml .reliant/workflows/failure-follow-up.yaml theme={null}
  - id: investigate
    type: workflow
    ref: builtin://agent
    args:
      mode: plan
    thread:
      mode: inherit
      inject:
        role: user
        content: |
          nightly-check run {{ inputs.failed_run }} failed. Run the checks,
          find the cause and report it. Do not change any files.
```

**3. Test the trigger with a scenario**

A scenario starts the run through the trigger with a sample payload, so the input mapping is tested without a real failure:

```yaml .reliant/workflows/failure-follow-up/scenarios/failed_run_gets_a_note.yaml theme={null}
name: failed_run_gets_a_note
trigger:
  name: nightly-check-failed
  payload: {run_id: run-123, outcome: failed, error: "Checks failed: FAIL: 2 tests failed"}
events: []
expect:
  outcome: completed
  completed: [note]
  messages:
    note:
      content_contains: ["nightly-check run run-123 failed."]
```

```bash terminal theme={null}
reliant workflow lint .reliant/workflows/failure-follow-up.yaml
reliant workflow scenario run
```

```text theme={null}
1 workflow(s): 0 lint error(s), 0 warning(s)
✅ All scenarios passed
```

Commit both files, so the machine syncs them. [Test workflows with scenarios](https://docs.reliantlabs.io/guides/workflows/test-workflows-with-scenarios.md) covers the format.

**4. Turn the trigger on**

Declaring a trigger fires nothing. Activate it for this project and machine, with the message each follow-up run starts with:

```bash terminal theme={null}
reliant trigger activate --workflow failure-follow-up --machine build-box \
  --name-prefix guides-sandbox-chain --message "Follow up on the failed nightly-check run."
```

```text theme={null}
TRIGGER               OUTCOME  ACTIVATION                                                                          NOTE
nightly-check-failed  enabled  guides-sandbox-chain · nightly-check-failed (35bcfc5f-7410-4dd6-800a-cda23d43821b)  -
```

**5. Verify a failure starts the follow-up**

Run the watched workflow, then list the trigger's firings:

```bash terminal theme={null}
reliant workflow run nightly-check --project-path .
reliant trigger events "guides-sandbox-chain · nightly-check-failed"
```

```text theme={null}
OCCURRED AT           OUTCOME   CHAT                                  DEFINITION
2026-11-20T16:06:36Z  launched  a24ea239-1817-5cb6-b403-71a262e33b85  machine build-box at .reliant/workflows/failure-follow-up.yaml @ master f687abe, clean …
```

`launched` with a chat ID is the follow-up run. `reliant workflow status a24ea239-1817-5cb6-b403-71a262e33b85` shows `Outcome: ✓ SUCCESS`, and the run's message in the app reads `nightly-check run bab4c621-d14c-4244-ba39-072766995a66 failed.`, naming the run that failed.

**6. Turn it off**

```bash terminal theme={null}
reliant trigger disable "guides-sandbox-chain · nightly-check-failed"   # pause; enable resumes it
reliant trigger delete "guides-sandbox-chain · nightly-check-failed"
```

## What this does not do

* **No loops.** A workflow-event trigger never fires on a run it started, or on that run's descendants, and a chain of event-started runs stops after five hops.
* **It watches only your own workflows' runs.** Leave `workflows` empty to watch all of them.
* **Nobody answers the follow-up.** Event-started runs are unattended: an agent in one decides and proceeds, and some tools are withheld from it ([Unattended by design](https://docs.reliantlabs.io/automations/overview.md#unattended-by-design)). In an organization, an agent follow-up spends only the organization's AI accounts.
* **`error` is not always filled.** It holds the error of a run that errored. For a run that ended at an `outcome: failure` node it is empty, so put what the follow-up needs in that node's message, or have the follow-up open the failed run.

## Troubleshooting

> [accordion] message is required: the declared trigger has no prompt, so the activation must write one
>
> `trigger activate` needs the first message for each run. Pass it with `--message`.

> [accordion] at least one user message or attachment is required
>
> Shown by `reliant trigger events` and `reliant trigger get` when the activation has no message. Check `Message:` in `reliant trigger get <name>`. If it is empty, delete the activation, remove `prompt:` from the declared trigger, and activate again with `--message`.

## Next steps

> [card] [Workflow events reference](https://docs.reliantlabs.io/automations/workflow-events.md)
>
> Every field, payload key and the loop limits.

> [card] [How automations fire](https://docs.reliantlabs.io/deep-dives/how-automations-fire.md)
>
> What happens between an event and the run it starts.

> [card] [Run an agent on a schedule](https://docs.reliantlabs.io/guides/workflows/run-an-agent-on-a-schedule.md)
>
> Start the workflow you are watching every night.

> [card] [Production alerts to GitHub issues](https://docs.reliantlabs.io/guides/workflows/production-alerts-to-github-issues.md)
>
> File an investigated issue when something breaks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.