Playbooks

Writing, editing, versioning, and running Ansible playbooks from the SculptOps interface.

The editor

SculptOps embeds a Monaco-based editor (the same engine as VS Code) with full YAML syntax highlighting. The editor auto-indents, highlights matching brackets, and underlines common YAML syntax errors inline.

Playbooks are stored in the database and are scoped to your organization. They are not stored on the filesystem of the host — all content lives in PostgreSQL.

Version history

Every save creates an immutable version entry. Open the History tab on any playbook to see a timestamped list of versions with who saved them. Click any version to open a read-only diff view comparing it to the current version, or click Restore to make it current (which itself creates a new version).

Note

Versions are never deleted automatically. You can manually delete old versions from the History tab if you want to reclaim space.

Importing from Git

Link a playbook to a GitHub, GitLab, or Bitbucket repository. Set the repository URL, branch, and file path, then click Git Sync to pull the latest version at any time. Private repositories are supported via personal access tokens (stored encrypted).

Playbooks can also be automatically synced when a push event is received via a webhook trigger.

Community library

Any playbook can be submitted to the shared community library directly from the editor. Click Details in the toolbar, then Submit to community. The form is pre-filled with the playbook’s name, content, description, and tags.

Community playbooks imported into your workspace display a Community badge and the original author’s name. See the Community Library page for full details.

Running a playbook

Run dialog options

InventoryWhich inventory (or specific groups within it) to target.
Extra varsJSON or YAML key-value pairs, equivalent to --extra-vars on the CLI.
Vault passwordSelect a stored vault credential if the playbook uses encrypted variables.
TagsComma-separated task tags to run (--tags).
Skip tagsComma-separated task tags to skip (--skip-tags).
LimitFurther restrict the host pattern (--limit), e.g. webservers[0].
Check modePass --check to do a dry run without making changes.
Diff modePass --diff to show file diffs for changed tasks.
VerbositySet -v / -vv / -vvv for more detailed output.

Execution lifecycle

When you click Execute, the following happens:

text

1. SculptOps writes a temporary inventory file
2. Spawns a Docker container with ANSIBLE_DOCKER_IMAGE
3. Mounts inventory, playbook, and SSH keys (read-only)
4. Runs ansible-playbook with your chosen options
5. Streams stdout/stderr via SSE to the browser
6. Container is removed on exit (success or failure)
7. Exit code and full log saved to the database

Real-time log colors

Greenok — task ran, no change
Yellowchanged — task made a change
Redfailed / unreachable — task failed
Cyanskipped — task was skipped
Blueincluded / meta — informational

Re-running executions

From Executions → History, any past execution can be re-run with the exact same parameters in one click. This is useful after a partial failure — fix the underlying issue and re-run without reconfiguring.

Playbook variables

Variables flow into playbooks from multiple sources, in ascending priority order:

text

inventory group vars
  → inventory host vars
    → extra vars from the run dialog
      → (highest) vault-decrypted vars

Variables defined at a higher priority override lower ones. Use the run dialog’s Extra vars field for one-off overrides without changing the playbook.

Limits and timeouts

Each execution is subject to the ANSIBLE_EXECUTION_TIMEOUT environment variable (default: 3600 seconds). If a playbook runs longer than this limit, the container is killed and the execution is marked as timed out. You can raise the timeout per-organization in Settings → Execution.

First Run

Inventory