From 88dd32b169bf4a5520115d3f6d1e4452aa621d57 Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Tue, 12 Apr 2022 12:19:39 +0200
Subject: [PATCH] Add stop/error script/automation action (#22338)

---
 source/_docs/scripts.markdown | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown
index 0b50140caee..db776b71460 100644
--- a/source/_docs/scripts.markdown
+++ b/source/_docs/scripts.markdown
@@ -710,6 +710,29 @@ automation:
 
 {% endraw %}
 
+## Stopping a script sequence
+
+It is possible to halt a script sequence at any point. Using the `stop` or
+`error` action.
+
+Both actions take a text as input explaining the reason for halting the
+sequence. This text will be logged and shows up in the automations and
+script traces.
+
+`stop` can be useful to halt a script halfway through a sequence when,
+for example, a condition is not met.
+
+```yaml
+- stop: "Stop running the rest of the sequence"
+```
+
+The `error` action stops a script as well, but marks the automation
+or script as failed to run.
+
+```yaml
+- error: "Well, that was unexpected!"
+```
+
 [Script component]: /integrations/script/
 [automations]: /getting-started/automation-action/
 [Alexa/Amazon Echo]: /integrations/alexa/