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.

Roles & collections

Each playbook can declare Ansible Galaxy dependencies in a requirements.yml via the Dependencies button in the editor toolbar. Before every run, SculptOps runs ansible-galaxy install on it, so the declared roles and collections are available to the play.

yaml

collections:
  - name: community.general
roles:
  - name: geerlingguy.docker

Leave it empty for playbooks with no external dependencies. Installing from Galaxy requires outbound network access; for isolated deployments, pre-bundle the roles and collections in a custom ANSIBLE_DOCKER_IMAGE instead.

Community library

Any playbook can be submitted to the shared community library. Open the Community Library from the Playbooks section and use Submit in its toolbar; 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

TargetRun against an inventory or a single server.
TagsComma-separated task tags to run (--tags).
Limit hostsFurther restrict the host pattern (--limit), e.g. webservers.
Vault passwordSelect a stored vault credential if the playbook uses encrypted variables.
Dry runPass --check to preview changes without applying them.
Extra varsKey/value pairs passed as --extra-vars.

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. Installs requirements.yml roles/collections with ansible-galaxy (if present)
5. Runs ansible-playbook with your chosen options
6. Streams stdout/stderr via SSE to the browser
7. Container is removed on exit (success or failure)
8. 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: