Bug 1394026 - Add docs for new action tasks definition format r=dustin
authorBrian Stack <bstack@mozilla.com>
Tue, 29 Aug 2017 10:53:13 -0700
changeset 377994 3ae0fa531315c6707205058f6a54a7cb7a027286
parent 377993 4a096ca3c342832295197c5f4e8c1b8c58ba11e2
child 377995 803a7a310b109b75db75bdd2e1787bee7cd9ab8c
push id50137
push userryanvm@gmail.com
push dateThu, 31 Aug 2017 15:39:08 +0000
treeherderautoland@3ae0fa531315 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdustin
bugs1394026
milestone57.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1394026 - Add docs for new action tasks definition format r=dustin MozReview-Commit-ID: IeB9QGwI761
taskcluster/docs/actions.rst
--- a/taskcluster/docs/actions.rst
+++ b/taskcluster/docs/actions.rst
@@ -205,18 +205,20 @@ Properties of ``parameters``  are docume
 ``parameters.yml`` artifact created by decisions tasks.
 
 
 Creating a Custom Action Task
 ------------------------------
 
 It is possible to define an action that doesn't take a callback. Instead, you'll
 then have to provide a task template. For details on how the task template
-language works refer to `the actions.json spec`_, the example below illustrates
-how to create such an action::
+language works refer to `the actions.json spec`_. There are two options for
+creating this sort of action in-tree. The first option is to create a yaml file
+and the second allows you to use Python to do some extra work if you'd like.
+The example below illustrates how to create such an action in Python::
 
   from registry import register_task_action
 
   @register_task_action(
       name='retrigger',
       title='Retrigger',
       description="Create a clone of the task",
       order=1,
@@ -248,16 +250,46 @@ how to create such an action::
               },
               ...
           },
           # It's now your responsibility to include treeherder routes, as well
           # additional metadata for treeherder in task.extra.treeherder.
           ...
       },
 
-This kind of action is useful for creating simple derivative tasks, but is
-limited by the expressiveness of the template language. On the other hand, it
-is more efficient than an action callback as it does not involve an
+An equivalent in yaml. Notice that we can't inspect parameters in this case::
+
+  ---
+  name: retrigger
+  title: Retrigger
+  description: Create a clone of the task
+  order: 1
+  context:
+    - platform: linux
+  input:
+    title: priority
+    description: Priority that should be given to the tasks
+    type: string
+    enum:
+      - low
+      - normal
+      - high
+    default: low'
+  ---
+  created: {'$fromNow': ''}
+  deadline: {'$fromNow': '1 hour'}
+  expires: {'$fromNow': '14 days'}
+  provisionerId: '...'
+  workerType: '...'
+  priority: '${input}'
+  payload:
+    command: '...'
+    env:
+      TASK_DEFINITION: {'$json': {'eval': 'task'}}
+
+These kinds of actions are useful for creating simple derivative tasks, but are
+limited by the expressiveness of the template language. On the other hand, they
+are more efficient than an action callback as they do not involve an
 intermediate action task before creating the task the user requested.
 
 For further details on the template language, see `the actions.json spec`_.
 
 .. _the actions.json spec: https://docs.taskcluster.net/manual/tasks/actions/spec