Ansible Start-at-Task Parameter

Ansible is a robust, open-source automation tool for configuration management, application deployment, and task automation. At the heart of Ansible are its playbooks which define a set of tasks that can be executed on remote machines.

Sometimes, you may not want to run the entire playbook, but instead run a subset or just a single task from the source playbook.

This is particularly useful when debugging the playbooks as you can step through each of the tasks in the playbook to determine which is causing an error, etc. Ansible has a command-line parameter called the start-at-task to achieve this functionality.

Therefore, in this tutorial, we will dive into the world of this parameter, determine what it does, and how we can use it to make our debugging process a little easier.


Before diving into the start-at-task feature, ensure that you have the following:

  • Installed Ansible on your machine
  • Basic understanding of Ansible playbooks

Ansible Start-at-Task Parameter

This is a handy parameter as it allows you to start the execution of a given playbook at a specific task while skipping all the preceding tasks.

The syntax of this parameter is as follows:

$ ansible-playbook playbook.yml --start-at-task="task_name"

Practical Example:

To better demonstrate how this parameter works, let us take a real-world playbook example as shown in the following YAML file:

- hosts: localhost
    - name: Task 1 - Create a directory
        path: /tmp/dir1
        state: directory
    - name: Task 2 - Create a file
        path: /tmp/dir1/file.yml
        state: touch
    - name: Task 3 - Install package
        name: nginx
        state: present

In the previous playbook, we have three distinct sets of tasks that perform the individual tasks. For example, the first task creates a directory, the second creates a file inside the (created) directory, and the last installs the Nginx server on the remote host.

However, let us say we already have the directory and the file created. In this case, we only need to install Nginx. We can use this parameter as shown in the following command:

$ ansible-playbook skip.yml --start-at-task="Task 3 - Install package"

This forces Ansible to skip Task 1 and Task 2.

Using Ansible Start-at-Task with Tags

We can also combine the Ansible tags with the start-at-tasks parameter and the –tags or –skip-tags for a more precise execution. An example is as follows:

- hosts: localhost
    - name: Task 1
        msg: "This is task 1"
        - debug

    - name: Task 2
        msg: "This is task 2"
        - setup
    - name: Task 3
        msg: "This is task 3"

To run the playbook starting at Task 2 but only for the tasks that are tagged with debug, we can use the following command:

$ ansible-playbook with_tags.yml --start-at-task="Task 2" --tags="debug"

This command starts the playbook at Task 2 but skips it since it doesn’t have the debug tag.

What You Should Know

There are some things to note about the start-at-task parameter. These include the following:

  1. The task name provided in the parameter should be an exact match, including the casing, to the one that is defined in the playbook.
  2. Second, if you have multiple tasks with a similar name inside the playbook, Ansible uses the first matching occurrence.


You learned about the start-at-task parameter in Ansible to introduce a more precise and granular way of controlling the execution flow of playbooks.

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list