Ansible Tags Survival Guide: How We Cut 20-Minute Playbooks to 90 Seconds

I still remember the Friday afternoon when our deployment pipeline broke. The playbook took 20 minutes to run, and the team was waiting to push a critical hotfix. The problem? We had no way to skip the 15-minute OS patch check that ran every single time, even when we only changed a config file. That's when I discovered Ansible tags—and it changed everything. Tags let you selectively execute parts of your playbook, turning a monolithic run into a surgical strike. In this article, I'll share how we use tags in production, including a real incident where a missing tag caused a 2-hour outage, and how to integrate tags with CI to run only changed components.

Tagging Tasks, Roles, and Blocks

Tagging is straightforward: add a tags: key to a task, role, or block. For tasks:

``yaml - name: Install nginx apt: name: nginx state: present tags: - packages - nginx ``

For roles, you can tag the role itself in the playbook:

``yaml - hosts: webservers roles: - role: nginx tags: - nginx - web ``

Blocks inherit tags to all tasks inside:

``yaml - name: Configure web server block: - name: Copy config template: ... - name: Restart service service: ... tags: - config ``

A gotcha: if you tag a block, the block itself is not a task, so --list-tasks won't show the block tag unless a task inside has it. Always tag individual tasks if you need precise control.

Using --tags and --skip-tags CLI Flags

The --tags flag filters execution to only tasks with specified tags. Multiple tags are comma-separated: --tags deploy,config. The --skip-tags flag excludes tasks with those tags. You can combine them: --tags deploy --skip-tags smoke-test runs deploy tasks but not smoke tests.

Important: --tags and --skip-tags are mutually exclusive in the sense that --skip-tags takes precedence. If a task has both a tag you include and a tag you skip, it will be skipped.

Use --list-tasks --tags deploy to preview what will run. This is invaluable for debugging: I once spent an hour wondering why a task wasn't running, only to find a typo in the tag name (deploy vs deply).

In CI, you can pass tags dynamically:

``bash ansible-playbook playbook.yml --tags "$TAGS" ``

Where $TAGS is set by your CI system based on changed files.

Special Tags: always and never

Ansible provides two special tags: always and never. Tags with always run regardless of the --tags filter (unless --skip-tags always is used). Tags with never are skipped unless explicitly included with --tags never.

Use always for critical setup tasks like creating users or directories that must exist for other tasks to work. Use never for optional or destructive tasks, like database resets.

Example:

```yaml - name: Create app user user: name: app tags: always

• name: Reset database
• shell: dropdb myapp
• tags: never
• ```

Gotcha: always does not override --skip-tags always. If you skip always, it won't run. Also, always tasks are not included when you use --tags without including always explicitly? Actually, they are included automatically. But if you use --tags foo, tasks with always still run. This is by design: always is additive.

However, if you use --skip-tags always, they are skipped. So be careful when skipping.

Tag Inheritance in Includes and Imports

When you include or import a file, tags can be applied at the include/import level. These tags propagate to all tasks in the included file. However, there's a nuance: include_tasks vs import_tasks.

With import_tasks, tags are applied statically at parse time. With include_tasks, tags are dynamic but still propagate.

Example:

``yaml - name: Include deploy tasks import_tasks: deploy.yml tags: - deploy ``

All tasks in deploy.yml will inherit the deploy tag. You can override this by using the apply keyword:

``yaml - name: Include with custom tags import_tasks: deploy.yml tags: - deploy apply: tags: - custom ``

This applies custom to all tasks, but they still also have deploy? Actually, apply replaces the inherited tags. So tasks will have only custom tag. This is a common source of confusion.

Best practice: Use import_tasks for static includes and apply tags at the include level. For dynamic includes, test carefully because tag inheritance can be unpredictable.

Strategy for Tagging in Large Playbooks

In large playbooks with hundreds of tasks, a consistent tagging strategy is essential. Here's our production approach:

1. Categorize by function: deploy, config, security, monitoring, cleanup.
2. Categorize by component: nginx, app, db, cache.
3. Use compound tags: deploy_app, config_nginx, security_patch.
4. Tag every task with at least one function tag.
5. Use always sparingly—only for tasks that must run every time (e.g., user creation).
6. Document tags in a README or use --list-tags in CI to generate docs.

Example tag structure:

``yaml tags: - deploy - app - config ``

This allows running --tags deploy for a full deploy, or --tags app for app-specific tasks, or --tags deploy,app for app deploy only.

Production insight: We maintain a tags.yml file that lists all tags and their purpose, checked into the repo. New team members must read it before modifying playbooks.

Using Tags in CI to Run Only Changed Components

In CI, you can determine which components changed and pass corresponding tags to Ansible. For example, if only the nginx directory changed, run only tasks tagged with nginx.

Here's a GitHub Actions workflow snippet:

```yaml - name: Detect changes id: changed uses: dorny/paths-filter@v2 with: filters: | nginx: - 'roles/nginx/' app: - 'app/' db: - 'roles/db/**'

• name: Run Ansible with tags
• run: |
• TAGS=""
• if [[ "${{ steps.changed.outputs.nginx }}" == "true" ]]; then TAGS="$TAGS,nginx"; fi
• if [[ "${{ steps.changed.outputs.app }}" == "true" ]]; then TAGS="$TAGS,app"; fi
• if [[ "${{ steps.changed.outputs.db }}" == "true" ]]; then TAGS="$TAGS,db"; fi
• TAGS=${TAGS#,}
• ansible-playbook playbook.yml --tags "$TAGS"
• ```

If no tags are set (no changes), you might want to run a default set of tags, or skip entirely. Use --tags always to run only always tasks, or --tags never to run nothing.

Gotcha: If you use --tags with an empty string, Ansible runs all tasks. So ensure you handle the empty case.

Tagging Handlers Correctly

Handlers are tasks that run when notified, but they have their own tags. If a handler is not tagged, it will only run if no --tags filter is applied. If you use --tags deploy, an untagged handler will not run even if notified.

Solution: Tag handlers with the same tags as the tasks that notify them, or use tags: always for critical handlers.

Example:

``yaml handlers: - name: restart nginx service: name: nginx state: restarted tags: - nginx - config ``

Now if you run --tags nginx, this handler will run when notified.

Gotcha: Even with correct tags, handlers only run at the end of the play. If you use --tags that exclude the handler's tag, it won't run. Always verify with --list-tasks.

Using --list-tags and --list-tasks for Debugging

These flags are your best friends for debugging tag issues. --list-tags shows all tags used in the playbook. --list-tasks shows tasks that will run, optionally filtered by --tags.

Example:

``bash ansible-playbook playbook.yml --list-tags ansible-playbook playbook.yml --list-tasks --tags deploy ``

The second command shows only tasks tagged with deploy. If a task you expect is missing, check its tag.

Production insight: I always run --list-tasks --tags mytag before a production deploy to confirm exactly what will execute. This caught many issues, like a new task accidentally tagged with never.

Common Pitfall: Tags and `--check` Mode

When using --check mode, tags still apply. So ansible-playbook playbook.yml --check --tags deploy will only check tasks tagged with deploy. This is useful for dry-running a subset.

However, --check does not run handlers. So if you're testing a handler tag, you won't see it in check mode. Use --list-tasks instead.

Production insight: We use --check --tags deploy in CI to validate syntax and task selection before actual deployment.

Tagging with `ansible-navigator`

If you use ansible-navigator (the TUI for Ansible), tags work the same way. You can pass --tags and --skip-tags as CLI arguments. In ansible-navigator's interactive mode, you can filter by tags using the :tags command.

Example:

``bash ansible-navigator run playbook.yml --tags deploy ``

Inside navigator, press : and type tags deploy to see only tagged tasks.

Tagging and Ansible Vault

Tags do not affect vault decryption. If you have vault-encrypted variables, they are decrypted regardless of tags. However, tasks that use those variables will only run if tagged appropriately.

Gotcha: If you run --tags deploy and a task with vault variables is not tagged deploy, it won't run, but the vault password will still be required because Ansible parses the entire playbook.

Advanced: Dynamic Tags with Variables

You can set tags using variables, but be careful: tags are evaluated at parse time for static imports, but dynamically for includes. This can lead to unexpected behavior.

Example:

``yaml - name: Run with dynamic tags include_tasks: somefile.yml tags: "{{ my_tags }}" ``

If my_tags is a list, it works. But if the variable is undefined, the task will fail. Use default() to provide a fallback.

Production insight: We avoid dynamic tags in static imports because they cause parse-time errors. For dynamic includes, we use them sparingly.