Task: Split Taskfiles with includes

Task includes import tasks from another Taskfile and expose them under a namespace prefix.

In a monorepo you do not want one giant Taskfile. includes lets each service keep its own Taskfile that the root file composes, with names prefixed by the namespace.

What it does

The includes map names other Taskfiles to import. Each include is given a namespace key; its tasks become callable as namespace:task. An include can set dir to run its tasks from a subdirectory, and optional: true so a missing file does not fail. This is how Task supports modular, per-project task definitions.

Common usage

Taskfile.yml

# Taskfile.yml (root)
version: '3'

includes:
  api:
    taskfile: ./services/api/Taskfile.yml
    dir: ./services/api
  web:
    taskfile: ./services/web/Taskfile.yml
    dir: ./services/web
  docs:
    taskfile: ./docs/Taskfile.yml
    optional: true

tasks:
  build:
    cmds:
      - task: api:build
      - task: web:build
# call directly: task api:test

Syntax

Key	What it does
includes:	Map of namespace to included Taskfile
taskfile: <path>	Path to the Taskfile to import
dir: <path>	Directory the included tasks run in
optional: true	Do not fail if the included file is missing
namespace:task	Call an included task by its prefixed name

In CI

Compose per-service Taskfiles with includes so each team owns its own file and the root file orchestrates them. Set dir so included tasks run with the right working directory, which matters for relative paths in CI checkouts.

Common errors in CI

"task: Failed to load Taskfile ... no such file or directory" means an include path is wrong relative to the root Taskfile; add optional: true only if the file is truly meant to be absent. "task: Task api:build does not exist" means the namespace or task name is misspelled. Relative paths inside an included task break if dir is not set.