Extending
A task can be used as a base template and extended. This is intended to reduce duplicate task definitions.
Extending tasks avoids a lot of duplicated task definitions in bigger projects and monorepos. With the extend property, a task uses another task's configuration as a template.
The following sections and examples use the two tasks in a build.tsc.yaml file, shown below. The catalog has a maintained tsc entry that you can include instead of copying.
tasks:
install:
src:
- package.json
- package-lock.json
generates:
- node_modules
cmds:
- npm ci
build:
deps: [ install ]
src:
- tsconfig.json
- src
cmds:
- node_modules/.bin/tsc
generates:
- distExtend a task
Extending tsc:build uses all of its properties as a base. If nothing else is defined, the result is an exact copy that runs in the working directory of the current build file.
tasks:
build:
extend: tsc:build
includes:
tsc: ./build.tsc.yamlOverride properties in an extend
An extending task can override any property, whether the base defines it or not. Single
values such as image, shell, cache and timeout are replaced by the extending
task's own value. Lists and maps are added to the base's instead:
| Property | With extend |
|---|---|
image, shell, cache, timeout | The task's own value replaces the base's. |
cmds, src, generates, mounts | The base's entries come first, the task's own follow. |
deps, needs | Both are used. |
envs, labels | Merged. The task's own value wins for a name both define. |
The envs of the base also include the top-level envs of the build file it comes from,
so a base that reads $NODE_VERSION keeps its default when you extend it.
tasks:
build:
extend: tsc:build
src:
- ../../tsconfig.base.json
includes:
tsc: ./build.tsc.yamlHere build runs the base's commands against the base's sources plus
../../tsconfig.base.json.
Container properties without an image
A task that extends a container task takes the base's image, so it may set mounts,
volumeSize and capAdd without an image of its own:
tasks:
build:
extend: base:node
mounts:
- .git
cmds:
- git log
includes:
base: ./build.base.yamlWhen neither the task nor its base has an image, they are an error:
task build sets mounts, but neither it nor its base has an image.
A base's volumeSize, capAdd, resources and secrets are not passed on; set them on
the extending task when it needs them.
Reset inherited values
To take nothing from the base for a property, name it in reset. The task's own value for
that property still applies. In this example the dependencies are cleared, so the task runs
without depending on install:
tasks:
build:
extend: tsc:build
reset: [deps]
includes:
tsc: ./build.tsc.yamlreset accepts deps, needs, src, generates, cmds, mounts, envs and labels.
It is an error without extend. An empty deps: [] does not clear the base's
dependencies, because the lists are added together.
Naming the base task
extend uses the same <prefix>:<task> addressing as dependencies:
the part before the colon is the include (or
reference) prefix, and the part after it is the task
name in that file. extend: tsc:build means "the build task from the file
included as tsc". To extend a task in the same file, use its bare name
(extend: build-base).