All jobs

Fix "The 'ansible.builtin.include' action plugin has been removed" in an Ansible playbook

Yes. An agent replaces each include with import_tasks or include_tasks, choosing by how tags, conditions and variables are used, and syntax-checks the result.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the playbook before it reads the error. credativ/ansible-playbook-patroni-debian deploys a Patroni cluster from Debian packages: patroni.yml has four plays, and seven of its task entries are the old include action. Lines 14 and 15 include tasks/set_dcs_ips.yml and tasks/set_pgsql_servers_ips.yml in the facts play; line 26 includes tasks/{{ dcs }}.yml, a file name built from the dcs variable that vars.yml sets to etcd; line 33 includes tasks/haproxy.yml; and lines 54 to 57 include tasks/consul.yml under when: dcs == "consul", then tasks/postgresql.yml and tasks/patroni.yml. The repository has tasks/etcd.yml, tasks/etcd3.yml, tasks/consul.yml and tasks/zookeeper.yml for the variable to choose from, an inventory with master, pg1, pg2 and pg3, and a README that runs it as ansible-playbook -i inventory patroni.yml.

On ansible-core 2.19.15, ansible-playbook --syntax-check stops at line 14 with the message in the title: Use include_tasks or import_tasks instead. This feature was removed from ansible-core in a release after 2023-05-16. The agent installs the releases on either side to say when: 2.15.13 accepts the playbook and prints [DEPRECATION WARNING]: "include" is deprecated, use include_tasks/import_tasks, and 2.16.14 refuses it with the same removal message. So the boundary is ansible-core 2.16, published 2023-11-06, and any control machine that upgraded past it runs nothing from this playbook.

Which replacement to use is the whole decision, and it is per line. import_tasks is read when the playbook is parsed, so tags and when on it apply to every task inside, and --list-tasks shows the imported tasks; include_tasks is read when the play reaches it, so a tag on the include applies to the include itself and the tasks inside are invisible to --list-tasks until they run. For the six fixed file names, import_tasks keeps the behaviour the old include had with tags, and the when: dcs == "consul" on line 54 then applies to each consul task, which is what the author meant. For line 26, the agent checks the variable case by running it: with import_tasks: tasks/{{ dcs }}.yml, --syntax-check passes and --list-tasks -i inventory lists 49 tasks across the four plays, including the etcd tasks, because dcs comes from vars_files and is known at parse time; with include_tasks on that line the same listing shows only include_tasks as a placeholder in the DCS play. Both work; the pull request uses import_tasks throughout and says why, with the include_tasks form named as the choice if dcs ever moves to inventory or host variables, where an import cannot read it.

The agent also runs the same check on anything else the removal touched. Nothing else in this repository uses include, the one import_tasks already present in the tasks files stays, and --syntax-check and --list-tasks both pass on 2.19.15 after the change. It records in the pull request that a syntax check and a task listing are what the sandbox can prove; the hosts named in the inventory are not reachable from it, so the playbook does not run against them.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Our playbook fails on the current ansible-core with \"The 'ansible.builtin.include' action plugin has been removed. Use include_tasks or import_tasks instead.\" Find every include of a task file in the playbooks and roles, with file and line, and for each note whether it carries tags, a when condition, a loop, or a variable in the file name. Install ansible-core releases to find the last release that still accepts include and the first that refuses it, and quote both messages. Replace each include: use import_tasks where tags or a condition must apply to the tasks inside and the file name is fixed or built from play variables, and include_tasks where the file name depends on inventory or host variables or the include sits inside a loop. For any variable file name, prove your choice by running ansible-playbook --list-tasks with the inventory and showing that the tasks resolve. Run --syntax-check on every playbook before and after. Do not run the playbook against any host. Open a pull request with the diff, the version findings, and the syntax-check and list-tasks output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes seven lines of patroni.yml, each include: becoming import_tasks: with its file name, condition and indentation untouched. The description names the releases on either side of the removal with their dates and quotes the deprecation warning from 2.15.13 and the error from 2.16.14. Below it is the --syntax-check output before and after, and the --list-tasks -i inventory output after, with the 49 tasks across the four plays so the reviewer can see that tasks/{{ dcs }}.yml resolved to the etcd file.

The reviewer checks the per-line choice: that every when which sat on an include now sits on an import_tasks, where it applies to the imported tasks, and that no replaced line sits inside a loop, where import_tasks is not allowed. The reviewer also reads the sentence about dcs: it is a play variable from vars.yml today, and the pull request says that moving it into the inventory would require include_tasks on that one line.

What the run does not do is deploy a cluster. The sandbox has no route to master or the pg hosts, and the pull request says that the next real run of the playbook, with the same inventory, is the reviewer's check that the imported tasks execute as the included ones did.

Run it on every control-machine upgrade that breaks a playbook

This error appears the first time a playbook runs from a machine or a CI image whose ansible-core moved past 2.16, as the first line of a failed job. A step in that job that runs only on failure can send the output to a Rush webhook trigger's URL with the trigger's secret in Authorization: Bearer; the text lands after the automation's saved prompt as the event, so the prompt tells the agent to read the playbook and line from it. Send an Idempotency-Key header to the trigger's URL set to the job's run id, so a retried job starts nothing new.

Playbooks that are run by hand have no job to fail. For those, a schedule trigger on an automation in the Project can run ansible-playbook --syntax-check on every playbook with the current ansible-core once a week, and open this pull request the week the check starts failing, before anyone needs the playbook in a hurry.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The choice between the two replacements depends on behaviour, not on syntax, and the way to settle it is to run the checks under each. A Rush sandbox installs 2.15.13, 2.16.14 and the current release to fix the boundary, then runs --syntax-check and --list-tasks with the repository's inventory under both forms of the variable include, so the pull request's claim that the etcd tasks resolve at parse time is an output, not an opinion.

An automation that holds a playbook's secrets and hosts is exactly where nobody wants a half-tested change. The run touches no host: it proves what can be proved from the checkout, the syntax and the task listing, and writes down what it could not, so the reviewer knows the first real run is still theirs.

Frequently asked questions

Which ansible-core release removed include?

ansible-core 2.16, published 2023-11-06. Checked by installing them, 2.15.13 still accepts the action and prints a deprecation warning naming include_tasks and import_tasks, and 2.16.14 refuses the playbook with the removal error, which says the feature was removed in a release after 2023-05-16.

Should I use import_tasks or include_tasks?

import_tasks when the file name is fixed or built from play variables and you want tags and when to reach the tasks inside, which is what the old include did; include_tasks when the file name depends on inventory or host variables or the include is inside a loop. In this playbook every line takes import_tasks, and the pull request says which line would change if the variable moved.

Can import_tasks take a file name with a variable in it?

When the variable is known at parse time. Here dcs comes from vars_files, and ansible-playbook --list-tasks with the inventory lists the etcd tasks under the DCS play, which shows the import resolved. A name that depends on a host's inventory variables needs include_tasks instead.

What happens to a when condition on the include?

With import_tasks it is applied to every imported task, so when: dcs == "consul" on the consul import skips each consul task on an etcd cluster. With include_tasks the condition decides whether the file is read at all. For this playbook the two give the same result, and the pull request picks the import for consistency with the other lines.

Does the agent run the playbook?

No. It runs --syntax-check and --list-tasks against the repository's inventory, which parse every task without connecting to a host. The hosts in the inventory are not reachable from the sandbox, and the pull request says the next real run is the reviewer's.

More Ansible jobs

More jobs like this: Fix a bug from an alert

Keep reading