Selecting Specific Tasks To Execute

Every long playbook has the same real-world problem: if task number 12 of 20 fails, fixing it shouldn’t mean re-running tasks 1 through 11 all over again. This chapter covers two tools for exactly that situation, before this section moves on to something more interactive.

The Problem: Re-Running A Long Playbook From The Beginning

A typo in a template variable causes task 12 to fail. You fix the typo. Re-running the whole playbook from task 1 means redoing eleven tasks that already succeeded — wasteful at best, and genuinely risky at worst if any of those earlier tasks have real side effects (a notification sent, a log entry appended) that shouldn’t happen twice.

--start-at-task: Resuming From A Specific Point

ansible-playbook site.yaml --start-at-task="Deploy main config from template"

Skips everything before the named task entirely, starting execution exactly there and continuing normally through everything after it — as though the earlier tasks had already run, without actually re-verifying that they did.

Matching Task Names Exactly

The string passed to --start-at-task matches against a task’s name: as written in the playbook. If a task’s name is templated — built from a loop variable, for instance — matching can behave less predictably than a plain static name. If there’s any task you might reasonably want to resume from individually later, give it a clear, unique, non-templated name up front. If the given name doesn’t match anything in the playbook at all, the run fails immediately with an error, rather than silently falling back to starting from the top.

--step: Confirming Each Task Before It Runs

ansible-playbook site.yaml --step

Before every single task, prompts interactively: Perform task: <task name> (y/n/c). y runs it, n skips it, c continues without further prompting for the rest of the run. Genuinely useful for cautiously walking through an unfamiliar or risky playbook one task at a time, confirming each one actually does what you expect before letting it proceed.

Combining The Two

ansible-playbook site.yaml --start-at-task="Deploy main config from template" --step

Resume from a specific point, and confirm each task from there onward individually — useful when you’re specifically troubleshooting the later portion of a long playbook and want fine control over exactly what happens from that point forward.

A Gotcha: --start-at-task Doesn’t Verify Anything Actually Happened

This is the crucial thing to understand before relying on it: --start-at-task doesn’t check or simulate that the earlier, skipped tasks genuinely succeeded — it simply begins execution at the named task, trusting that whatever state those earlier tasks would have produced is already in place.

If your fix for the original failure also depended on something an earlier task was supposed to set up — a variable from set_fact, a directory a file task should have created — and that task never actually completed successfully the first time around, the resumed run can fail in a new, confusing way, or worse, silently produce a wrong result with no obvious error at all.

Best Practices

• Use --start-at-task to avoid re-running already-successful, genuinely idempotent tasks — but verify, rather than assume, that everything the resumed task needs is actually already in place.
• Give tasks unique, clear, non-templated names if you anticipate ever wanting to resume from them individually — this keeps --start-at-task matching unambiguous.
• Use --step when cautiously walking through an unfamiliar or risky playbook for the first time, not as a routine habit for playbooks you already trust.
• Combine --start-at-task with --step when you want fine, deliberate control over just the later portion of a long run.