Create Tasks

If you’ve followed the tutorials, you may have a working Taskcluster + Taskgraph setup, but could be left wondering how to add a new task. This guide will teach you the basics of creating tasks!

Create a Kind

Before we can define tasks, we need to define a Kind. Kinds are groups of tasks that share some commonality with one another (how common they are depends on how you choose to organize them). So the first step is to define a kind for your task.

If we’re creating a build task, you might define a build kind by creating taskcluster/kinds/build/kind.yml. Simply creating this file is enough to define a kind, though in practice you’ll likely add extra configuration such as a loader or transforms.

Add Tasks to your Kind

Tasks are defined in the kind.yml under a tasks key. For example, our build-linux task might look like:

taskcluster/kinds/build/kind.yml

tasks:
  build-linux:
    description: "Build the app on Linux"
    worker-type: b-linux
    worker:
      docker-image: {in-tree: build}
    run:
      using: run-task
      cwd: '{checkout}'
      command: ./scripts/build.sh

If we want to add another task, say build-windows, we can just append it to the tasks object:

taskcluster/kinds/build/kind.yml

tasks:
  build-linux:
    description: "Build the app"
    worker-type: b-linux
    worker:
      docker-image: {in-tree: build}
    run:
      using: run-task
      cwd: '{checkout}'
      command: ./scripts/build.sh

  build-windows:
    description: "Build the app"
    worker-type: b-windows
    run:
      using: run-task
      cwd: '{checkout}'
      command: ./scripts/build.ps1

Note

The format of the tasks depends heavily on which transforms the kind uses. In this example, Taskgraph is implicitly adding the run and task transforms. See Transforms for more information.

Task Defaults

You may find that as you add more tasks, a certain amount of boilerplate gets copied from one task to the next. A task-defaults key can be used to reduce this overhead. The previous example can be re-written as:

taskcluster/kinds/build/kind.yml

task-defaults:
  description: "Build the app"
  run:
    using: run-task
    cwd: '{checkout}'

tasks:
  build-linux:
    worker-type: b-linux
    worker:
      docker-image: {in-tree: build}
    run:
      command: ./scripts/build.sh

  build-windows:
    worker-type: b-windows
    run:
      command: ./scripts/build.ps1

Using task-defaults recursively merges task configuration into the defaults for each task.

Tasks From

If you have a kind with a lot of tasks, the kind.yml file may grow to unmanageable sizes. To help mitigate this, you can use the tasks-from key. This allows you to define your tasks in any number of Yaml files outside of kind.yml. For example, the following example is equivalent to the previous two:

taskcluster/kinds/build/kind.yml

task-defaults:
  description: "Build the app"
  run:
    using: run-task
    cwd: '{checkout}'

tasks-from:
  - linux.yml
  - windows.yml

taskcluster/kinds/build/linux.yml

tasks:
  build-linux:
    worker-type: b-linux
    worker:
      docker-image: {in-tree: build}
    run:
      command: ./scripts/build.sh

taskcluster/kinds/build/windows.yml

tasks:
  build-windows:
    worker-type: b-windows
    run:
      command: ./scripts/build.ps1

All three of the previous examples should result in identical task definitions.

Further Reading

Next you may want to learn about using Transforms or how to Run Taskgraph Locally.