Payload Format


When submitting a task graph to the Task Cluster Queue (see createTask) you must provide a payload for defining the tasks to be executed by the worker. In the case of the generic worker, the payload must conform to the following schema.

Generic worker payload (source)

This schema defines the structure of the payload property referred to in a Taskcluster Task definition.

artifactsArray of

Artifacts to be published.

Since: generic-worker 1.0.0

contentTypestring

Explicitly set the value of the HTTP Content-Type response header when the artifact(s) is/are served over HTTP(S). If not provided (this property is optional) the worker will guess the content type of artifacts based on the filename extension of the file storing the artifact content. It does this by looking at the system filename-to-mimetype mappings defined in the Windows registry. Note, setting contentType on a directory artifact will apply the same contentType to all files contained in the directory.

See mime.TypeByExtension.

Since: generic-worker 10.4.0

expiresstringdate-time

Date when artifact should expire must be in the future, no earlier than task deadline, but no later than task expiry. If not set, defaults to task expiry.

Since: generic-worker 1.0.0

namestring

Name of the artifact, as it will be published. If not set, path will be used. Conventionally (although not enforced) path elements are forward slash separated. Example: public/build/a/house. Note, no scopes are required to read artifacts beginning public/. Artifact names not beginning public/ are scope-protected (caller requires scopes to download the artifact). See the Queue documentation for more information.

Since: generic-worker 8.1.0

pathstring

Relative path of the file/directory from the task directory. Note this is not an absolute path as is typically used in docker-worker, since the absolute task directory name is not known when the task is submitted. Example: dist\regedit.exe. It doesn't matter if forward slashes or backslashes are used.

Since: generic-worker 1.0.0

typestring
  • file
  • directory

Artifacts can be either an individual file or a directory containing potentially multiple files with recursively included subdirectories.

Since: generic-worker 1.0.0

commandArray of[1:∞]

One entry per command (consider each entry to be interpreted as a full line of a Windows™ .bat file). For example:

[
  "set",
  "echo hello world > hello_world.txt",
  "set GOPATH=C:\\Go"
]

Since: generic-worker 0.0.1

string
envObject of

Env vars must be string to string mappings (not number or boolean). For example:

{
  "PATH": "C:\\Windows\\system32;C:\\Windows",
  "GOOS": "windows",
  "FOO_ENABLE": "true",
  "BAR_TOTAL": "3"
}

Since: generic-worker 0.0.1

<string>string
featuresObject of

Feature flags enable additional functionality.

Since: generic-worker 5.3.0

chainOfTrustboolean

An artifact named public/chainOfTrust.json.asc should be generated which will include information for downstream tasks to build a level of trust for the artifacts produced by the task and the environment it ran in.

Since: generic-worker 5.3.0

taskclusterProxyboolean

The taskcluster proxy provides an easy and safe way to make authenticated taskcluster requests within the scope(s) of a particular task. See the github project for more information.

Since: generic-worker 10.6.0

maxRunTimeinteger[1:86400]

Maximum time the task container can run in seconds.

Since: generic-worker 0.0.1

mountsArray of

Directories and/or files to be mounted.

Since: generic-worker 5.4.0

MountOne of
File MountObject of
contentOne of

Content of the file to be mounted.

Since: generic-worker 5.4.0

Artifact ContentObject of

Requires scope queue:get-artifact:<artifact-name>.

Since: generic-worker 5.4.0

artifactstring[0:1024]
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
URL ContentObject of

URL to download content from.

Since: generic-worker 5.4.0

urlstringuri

URL to download content from.

Since: generic-worker 5.4.0

filestring

The filesystem location to mount the file.

Since: generic-worker 5.4.0

Writable Directory CacheObject of
cacheNamestring

Implies a read/write cache directory volume. A unique name for the cache volume. Requires scope generic-worker:cache:<cache-name>. Note if this cache is loaded from an artifact, you will also require scope queue:get-artifact:<artifact-name> to use this cache.

Since: generic-worker 5.4.0

ContentOne of

Optional content to be preloaded when initially creating the cache (if set, format must also be provided).

Since: generic-worker 5.4.0

Artifact ContentObject of

Requires scope queue:get-artifact:<artifact-name>.

Since: generic-worker 5.4.0

artifactstring[0:1024]
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
URL ContentObject of

URL to download content from.

Since: generic-worker 5.4.0

urlstringuri

URL to download content from.

Since: generic-worker 5.4.0

directorystring

The filesystem location to mount the directory volume.

Since: generic-worker 5.4.0

formatstring
  • rar
  • tar.bz2
  • tar.gz
  • zip

Archive format of the preloaded content (if content provided).

Since: generic-worker 5.4.0

Read Only DirectoryObject of
ContentOne of

Contents of read only directory.

Since: generic-worker 5.4.0

Artifact ContentObject of

Requires scope queue:get-artifact:<artifact-name>.

Since: generic-worker 5.4.0

artifactstring[0:1024]
taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
URL ContentObject of

URL to download content from.

Since: generic-worker 5.4.0

urlstringuri

URL to download content from.

Since: generic-worker 5.4.0

directorystring

The filesystem location to mount the directory volume.

Since: generic-worker 5.4.0

formatstring
  • rar
  • tar.bz2
  • tar.gz
  • zip

Archive format of content for read only directory.

Since: generic-worker 5.4.0

osGroupsArray of

A list of OS Groups that the task user should be a member of. Requires scope generic-worker:os-group:<os-group> for each group listed.

Since: generic-worker 6.0.0

string
rdpInfostring

Specifies an artifact name for publishing RDP connection information.

Since this is potentially sensitive data, care should be taken to publish to a suitably locked down path, such as login-identity/<login-identity>/rdpinfo.json which is only readable for the given login identity (for example `login-identity/mozilla-ldap/pmoore@mozilla.com/rdpInfo.txt`). See the artifact namespace guide for more information.

Use of this feature requires scope generic-worker:allow-rdp:<provisionerId>/<workerType> which must be declared as a task scope.

The RDP connection data is published during task startup so that a user may interact with the running task.

The task environment will be retained for 12 hours after the task completes, to enable an interactive user to perform investigative tasks. After these 12 hours, the worker will delete the task's Windows user account, and then continue with other tasks.

No guarantees are given about the resolution status of the interactive task, since the task is inherently non-reproducible and no automation should rely on this value.

Since: generic-worker 10.5.0

supersederUrlstringuri

URL of a service that can indicate tasks superseding this one; the current taskId will be appended as a query argument taskId. The service should return an object with a supersedes key containing a list of taskIds, including the supplied taskId. The tasks should be ordered such that each task supersedes all tasks appearing later in the list.

See superseding for more detail.

Since: generic-worker 10.2.2

The payload comprises of a command to run, environment variables to be set (optionally encrypted) and a timeout for the task (maxRunTime).

The worker will run the task, upload log files, and report back status to the Queue.