Skip to main content
A workflow that a trigger starts runs with nobody watching. A command that waits for input, a loop with no exit or a failure that tells no one shows up hours later, if at all. reliant workflow lint reads the workflow file and flags those steps before the first firing. This guide lints a nightly workflow with eight kinds of problem, then fixes each one. Lint is separate from validation. Validation asks whether a workflow can run. Lint asks whether it will still behave when nobody is watching it. Workflow lint describes every rule. This guide shows the ones an unattended workflow hits most.

Before you begin

  • The reliant CLI, v1.21 or later (reliant version). Lint needs no account and no network.
  • A workflow with triggers:. Run an AI agent on a schedule shows how to write one.
1

Lint a workflow written without unattended runs in mind

This workflow updates dependencies every night and has an agent fix whatever breaks. concurrency: {max_running: 1} lets only one run at a time, so a stuck run blocks every later night.
.reliant/workflows/nightly-deps.yaml
terminal
Each finding names its rule and the node, and ends with a link to the rule’s section of the docs (trimmed here). An error makes the command exit 1. A warning is printed and the command still exits 0. reliant workflow validate runs the same rules, so the same four errors fail validation too.
2

Bound every step that can hold the slot

With max_running, anything that can wait without limit is an error (slot-unbounded-wait). Without concurrency:, the same file gets warnings instead: [loop-unbounded] attempts and [run-no-timeout] on update and attempts.test.
  • Commands: give each run node a timeout:, the longest the command may take. Without one, it runs for the 30-day default.
  • The loop: add && iter.iteration < 3 to while, so a fix that never works ends after three rounds.
  • The agent: give it a turn limit. In v1.21.3 builtin://agent takes none, so the fixed version below uses builtin://structured-agent with max_turns: 60, the agent used for structured results in Write your first multi-agent workflow. Later releases accept max_turns on builtin://agent too: set it there and keep the agent. Left at 0 (no limit), lint names the arg to set, as a warning.
Then delete timeout: 45m from fix. A workflow node dispatches no activity of its own, so its timeout: bounds nothing (timeout-ignored).
3

Remove the step that approves its own gate

approve calls the approvals API with a saved token, so the workflow could approve requests, including the ones its own run raises. Lint cannot see what the token allows, so it treats any token that can decide approvals as able to (approval-decider). This workflow has no reason to approve anything, so delete the step.When approving is the job of a workflow, declare it with permissions: [approvals:decide] and allow the finding on that key, with the reason:
.reliant/workflows/approve-bot.yaml
A lint:allow with no reason is itself an error: [lint-allow-invalid] lint:allow approval-decider gives no reason.
4

Make every failure reach someone

  • Read the exit code. A non-zero exit does not fail a run node. Route update on nodes.update.exit_code, so a failed update goes to a failure ending instead of to the agent.
  • Add on_failure:. A run that fails, or ends at a node with outcome: failure, then saves a message that tells someone.
  • Declare the tools. requires: {tools: [npm]} makes a machine without npm fail before the first step, not halfway through.
  • Add scenarios for the trigger and both endings, as in Test AI agent workflows with scenarios.
5

Verify the workflow is clean

The fixed workflow:
.reliant/workflows/nightly-deps.yaml
With two scenarios in .reliant/workflows/nightly-deps/scenarios/ (the nightly firing ending at green, and three red rounds ending at still_red):
terminal
For CI, reliant workflow lint --json prints each finding’s rule, severity, node, message, fix and docs. To lint and validate in one gate, run reliant workflow validate --base origin/main, which also reports trigger changes that would break existing activations.

What this does not do

  • It does not stop a workflow from running. Lint never runs when a workflow is saved or started, so a rule added in a later release cannot stop an automation that already fires. Gate your repository on validate or lint yourself.
  • It reads only the file. Lint never runs the workflow, and it cannot see what a saved connection or a hosted secret can do. A clean lint does not mean every path works: that is what scenarios test.
  • It bounds steps, not spend. max_turns, loop bounds and timeouts cap how long each step runs. They do not set a token budget for the run.

Troubleshooting

Reliant releases before builtin://agent took max_turns report the agent this way, as an error whose fix text (editing the loop’s while) you cannot follow, because the loop is inside the built-in agent. On those, use builtin://structured-agent with max_turns. On a release whose finding reads “is bounded only by its max_turns input”, set args.max_turns on the node. Or, if you have judged that the agent’s run is bounded enough, allow the finding on the node with # lint:allow slot-unbounded-wait — <why>.
Write the reason after the rule ID: # lint:allow <rule> — <why it is fine here>. The rule ID must be one that reliant workflow lint --rules lists.
In reliant v1.21.3 the Warnings: count in the validate summary does not include lint warnings. Read the Lint warning: lines above the summary, or run reliant workflow lint, whose last line counts them.

Next steps

Test AI agent workflows with scenarios

Cover every trigger and ending with mocked runs.

Run an AI agent on a schedule

Turn the trigger on and watch its firings.

Loop an agent until tests pass

A bounded fix-and-test loop, step by step.

Workflow lint rules

Every rule, its severity and how to fix it.