The debops run/check commands

DebOps roles can store encrypted secrets (passwords and other confiential data) in a project directory, under ansible/secret/ subdirectory. For normal operation, the secrets need to be unlocked so that Ansible roles and playbooks can access and manipulate them. To make this process easier, DebOps provides the debops run and debops check commands which will automatically unlock and lock the encrypted secrets as needed.

An additional benefit of using these commands is that the user does not have to provide a full path to the playbooks - the script will try to find the correct playbook in a set of different directories or even inside Ansible Collections.

debops run

Execute one or more Ansible Playbooks against the Ansible inventory. Playbooks are included with the DebOps installation by default, they can be provided by Ansible Collections or stored in the ansible/playbooks/ subdirectory in the DebOps project directory. You can also specify full path to an Ansible playbook on disk.

The debops run command will automatically unlock and lock the encrypted ansible/secret/ directory as needed, to give the playbooks and roles access to secrets. If git-crypt is used for secret encryption, this process might fail if the project directory contains uncommitted changes. Easiest way to mitigate this is to unlock the project directory using the debops project unlock command before making any changes.


The options below need to be specified before any playbooks to take effect.

-h, --help

Display the help and usage information

--project-dir <project_dir>

Path to the project directory to work on. If it's not specified, the script will use the current directory.

-V <view>, --view <view>

Specify the name of the "infrastructure view" to use for running Ansible playbooks. If not specified, the default view will be used automatically. Using this option overrides the automatic view detection performed by DebOps based on the current working directory.

-E, --bell

Emit an ASCII "bell" at the end of the ansible-playbook command execution to notify the user. This might be useful during longer playbook runs.


Do not execute ansible-playbook command; instead print out all the environment variables and the command itself to stdout.

-v, --verbose

Increase output verbosity. More letters means higher verbosity.


Mark the end of the debops run options. Any of the options after this mark will be passed to the ansible-playbook command as-is.


Specify one or more Ansible Playbooks to execute.

If you specify simple names like site, service/core and similar, the script will look for the corresponding playbooks in the default Ansible Collection (debops.debops). If not found there, the ansible/playbooks/ subdirectory in the current DebOps project directory will be checked next. Finally the name will be assumed to be a normal filesystem path with optional .yml or .yaml extension.

You can also specify the namespace and collection at the start of the path to select a specific collection instead of the default one, for example debops.debops/site or debops.debops/service/core. The playbooks should be stored in the playbooks/ subdirectory of the Ansible Collection, you can use subdirectories to manage a large set of playbooks easier.


You can specify all arguments supported by the ansible-playbook command to augment the execution, for example --diff, --check, --limit, and so on. See ansible-playbook --help for more details.


Execute the site.yml DebOps playbook against all hosts in the Ansible inventory:

debops run site

Run the layer/common.yml DebOps playbook against specific hosts in the Ansible inventory. User will be notified at the end of playbook execution:

debops run -E layer/common -l webserver,dbserver,appserver

Display the commands which will run a DebOps playbook for a specific service on specific hosts:

debops run --eval service/mariadb_server -l dbservers

Do the same as above, by specifying the Ansible Collection in which to look for the playbook:

debops run --eval debops.debops/service/mariadb_server -l dbservers

Run a playbook from a custom Ansible Collection in a specific "infrastructure view" meant to be used to deploy an application:

debops run -V deployment company.collection/app/setup -l appservers

Run a playbook with DebOps in a verbose debug mode:

debops run -vvv service/sshd -l webserver

Same as above, but also enable verbose debug mode in Ansible itself:

debops run -vvv service/sshd -l webserver -vvv

debops check

Execute one or more Ansible Playbooks against the Ansible inventory in check mode. This command behaves the same as the debops run command, but automatically adds the --diff and --check ansible-playbook options to enable the "check mode". In this mode, Ansible will execute the playbook without making any actual changes to the host.