Add documentation on triggers yaml by joostlek · Pull Request #2884 · home-assistant/developers.home-assistant

joostlek · 2025-12-02T22:27:32Z

Proposed change

Add documentation on triggers yaml

Type of change

Document existing features within Home Assistant
Document new or changing features for which there is an existing pull request elsewhere
Spelling or grammatical corrections, or rewording for improved clarity
Changes to the backend of this documentation
Remove stale or deprecated documentation

Checklist

I have read and followed the documentation guidelines.
I have verified that my changes render correctly in the documentation.

Additional information

This PR fixes or closes issue: fixes #
Link to relevant existing code or pull request:

Summary by CodeRabbit

Documentation
- Reworked the Trigger class example to replace the prior generic EventTrigger with a concrete OccupancyClearedTrigger.
- Updated the trigger attachment example to show registering an occupancy-cleared callback and emitting a behavior-specific action payload (including entity_id and an occupancy-cleared description).
- Refreshed the “Trigger description” section with updated trigger registrations and YAML showing an occupancy_cleared trigger targeting a presence binary sensor, including the relevant selector configuration.

coderabbitai · 2026-06-23T17:18:48Z

📝 Walkthrough

Walkthrough

Updates docs/automations.md to replace the event-based trigger example with an occupancy-cleared trigger example, including the trigger class, runner callback, trigger registration, and YAML description.

Changes

Automation trigger documentation

Layer / File(s)	Summary
Trigger class and schema `docs/automations.md`	`EventTrigger` is replaced by `OccupancyClearedTrigger`, and the example config schema now requires `CONF_TARGET` instead of the previous event-options shape.
Runner callback `docs/automations.md`	The attached runner example replaces the generic event callback with an occupancy-cleared callback that builds a payload from `entity_id` and registers it with the occupancy-cleared listener placeholder.
Trigger registration and description `docs/automations.md`	`async_get_triggers` returns `occupancy_cleared` for `OccupancyClearedTrigger`, and the YAML snippet documents an occupancy-cleared trigger targeting a binary sensor with `device_class: presence`.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested reviewers

frenck

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding trigger YAML documentation.
Description check	✅ Passed	The description follows the template and covers the main change, though the checklist and additional information fields are left incomplete.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

♻️ Duplicate comments (1)

docs/automations.md (1)
99-100: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Broaden the usage note.

triggers.yaml descriptions are also consumed by the core get_triggers_for_target websocket API, so this sentence is too narrow. Update it to mention both frontend and backend consumers. As per path instructions, keep Markdown guidance direct and authoritative.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/automations.md` around lines 99 - 100, The current description of
triggers.yaml only mentions frontend usage as an example, but the core
get_triggers_for_target websocket API also consumes these descriptions from the
backend. Expand the usage note to mention both frontend and backend consumers of
the triggers.yaml file, specifically including reference to the
get_triggers_for_target websocket API. Keep the language direct and
authoritative as per Markdown documentation standards.
Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@docs/automations.md`:
- Around line 99-100: The current description of triggers.yaml only mentions
frontend usage as an example, but the core get_triggers_for_target websocket API
also consumes these descriptions from the backend. Expand the usage note to
mention both frontend and backend consumers of the triggers.yaml file,
specifically including reference to the get_triggers_for_target websocket API.
Keep the language direct and authoritative as per Markdown documentation
standards.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2573572d-fca1-4ae2-a170-77a822cf1bfb

📥 Commits

Reviewing files that changed from the base of the PR and between 2d91792 and 0a04d7c.

📒 Files selected for processing (1)

docs/automations.md

abmantis

As you pointed out in #2884 (comment) we should make the python code and the yaml description match, otherwise it becomes confusing for a new contributor to follow.

home-assistant · 2026-06-23T21:44:13Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

abmantis

Since we should add docs in the future for the new trigger helpers (that handle target + behavior), maybe keep behavior out of this one? Currently it has behavior but not using the standard selector.
You can check the todo integration for an example of a trigger that extends the base Trigger class directly and does not have behavior (but has target).

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/automations.md`:
- Line 96: The `triggers.yaml` usage description under the automations docs is
too narrow and only mentions the frontend; update the wording to reflect that
trigger descriptions are also consumed by core APIs. Edit the sentence in the
automations documentation so it explicitly references both the frontend and core
API usage, and include `get_triggers_for_target` as the example symbol to make
the scope clear.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 26220623-5c41-4f1c-bafb-19b30f4ba558

📥 Commits

Reviewing files that changed from the base of the PR and between 6e71e65 and 4ac785d.

📒 Files selected for processing (1)

docs/automations.md

coderabbitai · 2026-06-29T13:57:44Z


+### Trigger description
+
+Triggers should have their description in a `triggers.yaml` file. The description specifies the structure of the triggers and is used by the frontend, for example.


📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Update triggers.yaml usage description to include core API, not just frontend.

Past review feedback noted that triggers.yaml descriptions are also used in core via the get_triggers_for_target websocket API, not only the frontend. The current text "and is used by the frontend, for example" understates the usage. Consider: "The description specifies the structure of the triggers and is used by the frontend and core APIs, such as get_triggers_for_target."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/automations.md` at line 96, The `triggers.yaml` usage description under the automations docs is too narrow and only mentions the frontend; update the wording to reflect that trigger descriptions are also consumed by core APIs. Edit the sentence in the automations documentation so it explicitly references both the frontend and core API usage, and include `get_triggers_for_target` as the example symbol to make the scope clear.

abmantis

Thanks!

Add documentation on triggers yaml

1682743

joostlek requested review from abmantis and emontnemery December 2, 2025 22:27

joostlek commented Dec 2, 2025

View reviewed changes

Comment thread docs/automations.md Outdated

abmantis requested changes Dec 3, 2025

View reviewed changes

Comment thread docs/automations.md Outdated

Comment thread docs/automations.md Outdated

joostlek added 3 commits June 8, 2026 15:23

Merge branch 'master' into trigger

954f01c

Fix comments

a13f49a

Fix

0a04d7c

joostlek marked this pull request as ready for review June 23, 2026 17:15

coderabbitai Bot reviewed Jun 23, 2026

View reviewed changes

abmantis requested changes Jun 23, 2026

View reviewed changes

Comment thread docs/automations.md Outdated

Comment thread docs/automations.md Outdated

Comment thread docs/automations.md Outdated

home-assistant Bot marked this pull request as draft June 23, 2026 21:44

Fix

6e71e65

joostlek marked this pull request as ready for review June 23, 2026 21:56

home-assistant Bot requested a review from abmantis June 23, 2026 21:57

Merge branch 'master' into trigger

96362d3

abmantis requested changes Jun 24, 2026

View reviewed changes

Comment thread docs/automations.md Outdated

Comment thread docs/automations.md Outdated

Comment thread docs/automations.md Outdated

home-assistant Bot marked this pull request as draft June 24, 2026 16:43

Fix

4ac785d

joostlek marked this pull request as ready for review June 29, 2026 13:55

home-assistant Bot requested a review from abmantis June 29, 2026 13:55

coderabbitai Bot reviewed Jun 29, 2026

View reviewed changes

abmantis approved these changes Jun 30, 2026

View reviewed changes

abmantis merged commit d486f71 into home-assistant:master Jun 30, 2026
5 checks passed


		### Trigger description

		Triggers should have their description in a `triggers.yaml` file. The description specifies the structure of the triggers and is used by the frontend, for example.

Uh oh!

Uh oh!

Conversation

joostlek commented Dec 2, 2025 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Checklist

Additional information

Summary by CodeRabbit

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested reviewers

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

abmantis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

home-assistant Bot commented Jun 23, 2026

Uh oh!

abmantis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

abmantis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joostlek commented Dec 2, 2025 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 23, 2026 •

edited

Loading