bvandeusen/FabledSteward

Fork 0

Files

T

bvandeusen 42f7840c26

CI / lint (push) Successful in 2s

Details

CI / unit (push) Successful in 8s

Details

CI / integration (push) Successful in 2m14s

Details

CI / publish (push) Successful in 59s

Details

feat(ansible): steward:category + steward:confirm playbook metadata

Extend the playbook metadata convention with a namespaced `# steward:<key>:`
comment block:

- steward:category — free-text grouping label, shown as a badge in the browse
  list and on the run form.
- steward:confirm — true/yes/1/on marks a playbook destructive; the run form
  then requires a confirmation tick (required checkbox in the shared vars
  fragment) before it can launch.

sources.discover_playbook_meta() parses description + category + confirm (first
match per key; `# description:` still primary, `# steward:description:` alias).
discover_playbook_description() now delegates to it. The browse list reads
per-playbook meta to show category badges + descriptions; the run-form and
playbook-vars fragments render the badge + confirm gate.

Bundled playbooks tagged: docker_prune → category maintenance + confirm true;
provision/install/update → category host-agent.

Docs: docs/reference/playbook-authoring.md updated (keys now implemented) and a
quick reference added next to the code at steward/ansible/PLAYBOOK_CONVENTIONS.md.
Tests added for category/confirm/alias parsing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-17 11:35:35 -04:00

1.9 KiB

Raw Blame History

Steward playbook conventions (quick reference)

What Steward reads from a playbook in this subsystem. Full guide: docs/reference/playbook-authoring.md. Parser: steward/ansible/sources.py — discover_playbook_meta() and discover_playbook_variables().

Magic comments (metadata)

---
# description: One line on what this playbook does.   # shown on selection
# steward:category: maintenance                       # grouping badge
# steward:confirm: true                               # require confirm to run
- name: …            # used as the description if no `# description:` comment
  hosts: all         # Steward generates the inventory from the chosen target/group

# description: — first match wins; case-insensitive; falls back to first play name:.
# steward:<key>: <value> — namespaced metadata. Implemented keys:
- category — free-text grouping label (badge in browse + run form).
- confirm — true/yes/1/on → run form requires a confirmation tick.
- description — alias for # description: (unprefixed wins if both present).
- Unknown # steward:* keys are ignored (namespace reserved for future use).

Structural cues (no comments needed)

vars: scalars → editable run-time fields (default shown as placeholder; blank = keep default; values sent as highest-precedence extra-vars).
vars_prompt: → run-time fields (required when no default; private: true → masked).
Secret naming — a var whose name contains password/passwd/secret/ token/api_key/private_key/credential is masked and not persisted.
hosts: all — target via the run form's scope; don't hardcode hosts.
Credentials — never embed them. Steward connects as the managed steward account (passwordless sudo; use become: true) or one-time bootstrap creds.

Be idempotent — Steward re-runs playbooks (updates, schedules, retries).

1.9 KiB Raw Blame History

Steward playbook conventions (quick reference)

Magic comments (metadata)

Structural cues (no comments needed)

1.9 KiB

Raw Blame History