Queue API Documentation


BaseUrl
https://queue.taskcluster.net/v1

The queue, typically available at queue.taskcluster.net, is responsible for accepting tasks and track their state as they are executed by workers. In order ensure they are eventually resolved.

This document describes the API end-points offered by the queue. These end-points targets the following audience:

  • Schedulers, who create tasks to be executed,
  • Workers, who execute tasks, and
  • Tools, that wants to inspect the state of a task.

Functions

Using the APIs
SignatureSummary
task(taskId) : resultGet Task Definition
status(taskId) : resultGet task status
listTaskGroup(taskGroupId, {continuationToken, limit}) : resultList Task Group
listDependentTasks(taskId, {continuationToken, limit}) : resultList Dependent Tasks
createTask(taskId, payload) : resultCreate New Task
defineTask(taskId, payload) : resultDefine Task
scheduleTask(taskId) : resultSchedule Defined Task
rerunTask(taskId) : resultRerun a Resolved Task
cancelTask(taskId) : resultCancel Task
pollTaskUrls(provisionerId, workerType) : resultGet Urls to Poll Pending Tasks
claimWork(provisionerId, workerType, payload) : resultClaim Work
claimTask(taskId, runId, payload) : resultClaim Task
reclaimTask(taskId, runId) : resultReclaim task
reportCompleted(taskId, runId) : resultReport Run Completed
reportFailed(taskId, runId) : resultReport Run Failed
reportException(taskId, runId, payload) : resultReport Task Exception
createArtifact(taskId, runId, name, payload) : resultCreate Artifact
completeArtifact(taskId, runId, name, payload) : voidComplete Artifact
getArtifact(taskId, runId, name) : voidGet Artifact from Run
getLatestArtifact(taskId, name) : voidGet Artifact from Latest Run
listArtifacts(taskId, runId, {continuationToken, limit}) : resultGet Artifacts from Run
listLatestArtifacts(taskId, {continuationToken, limit}) : resultGet Artifacts from Latest Run
listProvisioners({continuationToken, limit}) : resultGet a list of all active provisioners
getProvisioner(provisionerId) : resultGet an active provisioner
declareProvisioner(provisionerId, payload) : resultUpdate a provisioner
pendingTasks(provisionerId, workerType) : resultGet Number of Pending Tasks
listWorkerTypes(provisionerId, {continuationToken, limit}) : resultGet a list of all active worker-types
getWorkerType(provisionerId, workerType) : resultGet a worker-type
declareWorkerType(provisionerId, workerType, payload) : resultUpdate a worker-type
listWorkers(provisionerId, workerType, {continuationToken, limit, quarantined}) : resultGet a list of all active workers of a workerType
getWorker(provisionerId, workerType, workerGroup, workerId) : resultGet a worker-type
quarantineWorker(provisionerId, workerType, workerGroup, workerId, payload) : resultQuarantine a worker
declareWorker(provisionerId, workerType, workerGroup, workerId, payload) : resultDeclare a worker
ping() : voidPing Server

Get Task Definition

Method
get
Route
/task/<taskId>
Signature
task(taskId) : result
Stability
stable

This end-point will return the task-definition. Notice that the task definition may have been modified by queue, if an optional property is not specified the queue may provide a default value.

Response

Task Definition Response (source)

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Along with the taskGroupId this is used to form the permission scope queue:assume:scheduler-id:<schedulerId>/<taskGroupId>, this scope is necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]

List of task specific routes, AMQP messages will be CC'ed to these routes.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest

Priority of task, this defaults to lowest and the scope queue:create-task:<priority>/<provisionerId>/<workerType> is required to define a task with <priority>.

retriesinteger[0:49]

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces.

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯


Get task status

Method
get
Route
/task/<taskId>/status
Signature
status(taskId) : result
Stability
stable

Get task status structure from taskId

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



List Task Group

Method
get
Route
/task-group/<taskGroupId>/list
Signature
listTaskGroup(taskGroupId, {continuationToken, limit}) : result
Stability
stable

List tasks sharing the same taskGroupId.

As a task-group may contain an unbounded number of tasks, this end-point may return a continuationToken. To continue listing tasks you must call the listTaskGroup again with the continuationToken as the query-string option continuationToken.

By default this end-point will try to return up to 1000 members in one request. But it may return less, even if more tasks are available. It may also return a continuationToken even though there are no more results. However, you can only be sure to have seen all results if you keep calling listTaskGroup with the last continuationToken until you get a result without a continuationToken.

If you are not interested in listing all the members at once, you may use the query-string option limit to return fewer.

Response

List Task-Group Response (source)

Response from a listTaskGroup request.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for the task-group being listed.

tasksArray of

List of tasks in this task-group.

taskObject of

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Along with the taskGroupId this is used to form the permission scope queue:assume:scheduler-id:<schedulerId>/<taskGroupId>, this scope is necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]

List of task specific routes, AMQP messages will be CC'ed to these routes.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest

Priority of task, this defaults to lowest and the scope queue:create-task:<priority>/<provisionerId>/<workerType> is required to define a task with <priority>.

retriesinteger[0:49]

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces.

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯
statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of tasks in the task-group. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called listTaskGroup with continuationToken until you get a result without a continuationToken.



List Dependent Tasks

Method
get
Route
/task/<taskId>/dependents
Signature
listDependentTasks(taskId, {continuationToken, limit}) : result
Stability
stable

List tasks that depend on the given taskId.

As many tasks from different task-groups may dependent on a single tasks, this end-point may return a continuationToken. To continue listing tasks you must call listDependentTasks again with the continuationToken as the query-string option continuationToken.

By default this end-point will try to return up to 1000 tasks in one request. But it may return less, even if more tasks are available. It may also return a continuationToken even though there are no more results. However, you can only be sure to have seen all results if you keep calling listDependentTasks with the last continuationToken until you get a result without a continuationToken.

If you are not interested in listing all the tasks at once, you may use the query-string option limit to return fewer.

Response

List Dependent Tasks Response (source)

Response from a listDependentTasks request.

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for the task whose dependents are being listed.

tasksArray of

List of tasks that have taskId in the task.dependencies property.

taskObject of

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Along with the taskGroupId this is used to form the permission scope queue:assume:scheduler-id:<schedulerId>/<taskGroupId>, this scope is necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]

List of task specific routes, AMQP messages will be CC'ed to these routes.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest

Priority of task, this defaults to lowest and the scope queue:create-task:<priority>/<provisionerId>/<workerType> is required to define a task with <priority>.

retriesinteger[0:49]

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces.

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯
statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of dependent tasks. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called listDependentTasks with continuationToken until you get a result without a continuationToken.



Create New Task

Method
put
Route
/task/<taskId>
Scopes
all of
for each  scope in  scopes
<scope>
and
for each  route in  routes
queue:route:<route>
and
any of
all of
queue:scheduler-id:<schedulerId> and
any of
for each  priority in  priorities
queue:create-task:<priority>:<provisionerId>/<workerType>
or
if  legacyScopes
any of
queue:create-task:<provisionerId>/<workerType> or
all of
queue:define-task:<provisionerId>/<workerType> and
queue:task-group-id:<schedulerId>/<taskGroupId> and
queue:schedule-task:<schedulerId>/<taskGroupId>/<taskId>
Signature
createTask(taskId, payload) : result
Stability
stable

Create a new task, this is an idempotent operation, so repeat it if you get an internal server error or network connection is dropped.

Task `deadline´, the deadline property can be no more than 5 days into the future. This is to limit the amount of pending tasks not being taken care of. Ideally, you should use a much shorter deadline.

Task expiration, the expires property must be greater than the task deadline. If not provided it will default to deadline + one year. Notice, that artifacts created by task must expire before the task.

Task specific routing-keys, using the task.routes property you may define task specific routing-keys. If a task has a task specific routing-key: <route>, then when the AMQP message about the task is published, the message will be CC'ed with the routing-key: route.<route>. This is useful if you want another component to listen for completed tasks you have posted. The caller must have scope queue:route:<route> for each route.

Dependencies, any tasks referenced in task.dependencies must have already been created at the time of this call.

Important Any scopes the task requires are also required for creating the task. Please see the Request Payload (Task Definition) for details.

Request Payload

Task Definition Request (source)

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]
default:

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
default: all-completed
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: lowest
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest
  • normal

Priority of task, this defaults to lowest, equivalent to the deprecated normal. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of
default: [object Object]

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Define Task

(deprecated)

Method
post
Route
/task/<taskId>/define
Scopes
all of
for each  scope in  scopes
<scope>
and
for each  route in  routes
queue:route:<route>
and
any of
all of
queue:scheduler-id:<schedulerId> and
any of
for each  priority in  priorities
queue:create-task:<priority>:<provisionerId>/<workerType>
or
if  legacyScopes
any of
queue:define-task:<provisionerId>/<workerType> or
queue:create-task:<provisionerId>/<workerType> or
all of
queue:define-task:<provisionerId>/<workerType> and
queue:task-group-id:<schedulerId>/<taskGroupId>
Signature
defineTask(taskId, payload) : result
Stability
deprecated

Deprecated, this is the same as createTask with a self-dependency. This is only present for legacy.

Request Payload

Task Definition Request (source)

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]
default: -
^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Task submitter required scopes queue:assume:scheduler-id:<schedulerId>/<taskGroupId>. This scope is also necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]
default:

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
default: all-completed
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]
default:

List of task specific routes, AMQP messages will be CC'ed to these routes. Task submitter required scopes queue:route:<route> for each route given.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
default: lowest
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest
  • normal

Priority of task, this defaults to lowest, equivalent to the deprecated normal. Task submitter required scopes queue:task-priority:high for high priority tasks.

retriesinteger[0:49]
default: 5

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of
default:

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces. Task submitter required scopes The same scope-pattern(s) given (otherwise a task could be submitted to perform an action that the task submitter is not authorized to perform).

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of
default: [object Object]

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Schedule Defined Task

Method
post
Route
/task/<taskId>/schedule
Scopes
any of
queue:schedule-task:<schedulerId>/<taskGroupId>/<taskId> or
all of
queue:schedule-task and
assume:scheduler-id:<schedulerId>/<taskGroupId>
Signature
scheduleTask(taskId) : result
Stability
stable

scheduleTask will schedule a task to be executed, even if it has unresolved dependencies. A task would otherwise only be scheduled if its dependencies were resolved.

This is useful if you have defined a task that depends on itself or on some other task that has not been resolved, but you wish the task to be scheduled immediately.

This will announce the task as pending and workers will be allowed to claim it and resolve the task.

Note this operation is idempotent and will not fail or complain if called with a taskId that is already scheduled, or even resolved. To reschedule a task previously resolved, use rerunTask.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Rerun a Resolved Task

(deprecated)

Method
post
Route
/task/<taskId>/rerun
Scopes
any of
queue:rerun-task:<schedulerId>/<taskGroupId>/<taskId> or
all of
queue:rerun-task and
assume:scheduler-id:<schedulerId>/<taskGroupId>
Signature
rerunTask(taskId) : result
Stability
deprecated

This method reruns a previously resolved task, even if it was completed. This is useful if your task completes unsuccessfully, and you just want to run it from scratch again. This will also reset the number of retries allowed.

Remember that retries in the task status counts the number of runs that the queue have started because the worker stopped responding, for example because a spot node died.

Remark this operation is idempotent, if you try to rerun a task that is not either failed or completed, this operation will just return the current task status.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Cancel Task

Method
post
Route
/task/<taskId>/cancel
Scopes
any of
queue:cancel-task:<schedulerId>/<taskGroupId>/<taskId> or
all of
queue:cancel-task and
assume:scheduler-id:<schedulerId>/<taskGroupId>
Signature
cancelTask(taskId) : result
Stability
stable

This method will cancel a task that is either unscheduled, pending or running. It will resolve the current run as exception with reasonResolved set to canceled. If the task isn't scheduled yet, ie. it doesn't have any runs, an initial run will be added and resolved as described above. Hence, after canceling a task, it cannot be scheduled with queue.scheduleTask, but a new run can be created with queue.rerun. These semantics is equivalent to calling queue.scheduleTask immediately followed by queue.cancelTask.

Remark this operation is idempotent, if you try to cancel a task that isn't unscheduled, pending or running, this operation will just return the current task status.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Get Urls to Poll Pending Tasks

Method
get
Route
/poll-task-url/<provisionerId>/<workerType>
Scopes
any of
queue:poll-task-urls:<provisionerId>/<workerType> or
all of
queue:poll-task-urls and
assume:worker-type:<provisionerId>/<workerType>
Signature
pollTaskUrls(provisionerId, workerType) : result
Stability
stable

Get a signed URLs to get and delete messages from azure queue. Once messages are polled from here, you can claim the referenced task with claimTask, and afterwards you should always delete the message.

Response

Poll Task Urls Response (source)

Response to request for poll task urls.

queuesArray of

List of signed URLs for queues to poll tasks from, they must be called in the order they are given. As the first entry in this array may have higher priority.

signedPollUrlstringuri

Signed URL to get message from the Azure Queue Storage queue, that holds messages for the given provisionerId and workerType. Note that this URL returns XML, see documentation for the Azure Queue Storage REST API for details. When you have a message you can use claimTask to claim the task. You will need to parse the XML response and base64 decode and JSON parse the MessageText. After you have called claimTask you must us the signedDeleteUrl to delete the message. Remark, you are allowed to append &numofmessages=N, where N < 32, to the URLs if you wish to obtain more than one message at the time.

signedDeleteUrlstring^https://

Signed URL to delete messages that have been received using the signedPollUrl. You must do this to avoid receiving the same message again. To use this URL you must substitute {{messageId}} and {{popReceipt}} with MessageId and PopReceipt from the XML response the signedPollUrl gave you. It is important that you encodeURIComponent both MessageId and PopReceipt prior to substitution, otherwise you will experience intermittent failures! Note this URL only works with DELETE request.

expiresstringdate-time

Date and time after which the signed URLs provided in this response expires and not longer works for authentication.



Claim Work

Method
post
Route
/claim-work/<provisionerId>/<workerType>
Scopes
all of
queue:claim-work:<provisionerId>/<workerType> and
queue:worker-id:<workerGroup>/<workerId>
Signature
claimWork(provisionerId, workerType, payload) : result
Stability
stable

Claim any task, more to be added later... long polling up to 20s.

Request Payload

Claim Work Request (source)

Request to claim a task for a worker to process.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker claiming the task is a part of.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker within the given workerGroup

tasksinteger[1:32]
default: 1

Number of tasks to attempt to claim.

Response

Claim Work Response (source)

Response to an attempt to claim tasks for a worker to process.

tasksArray of

List of task claims, may be empty if no tasks was claimed, in which case the worker should sleep a tiny bit before polling again.

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.

runIdinteger[0:1000]

run-id assigned to this run of the task

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker-group within which this run started.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker executing this run.

takenUntilstringdate-time

Time at which the run expires and is resolved as exception, with reason claim-expired if the run haven't been reclaimed.

taskObject of

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Along with the taskGroupId this is used to form the permission scope queue:assume:scheduler-id:<schedulerId>/<taskGroupId>, this scope is necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]

List of task specific routes, AMQP messages will be CC'ed to these routes.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest

Priority of task, this defaults to lowest and the scope queue:create-task:<priority>/<provisionerId>/<workerType> is required to define a task with <priority>.

retriesinteger[0:49]

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces.

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯
credentialsObject of

Temporary credentials granting task.scopes and the scope: queue:claim-task:<taskId>/<runId> which allows the worker to reclaim the task, upload artifacts and report task resolution.

The temporary credentials are set to expire after takenUntil. They won't expire exactly at takenUntil but shortly after, hence, requests coming close takenUntil won't have problems even if there is a little clock drift.

Workers should use these credentials when making requests on behalf of a task. This includes requests to create artifacts, reclaiming the task reporting the task completed, failed or exception.

Note, a new set of temporary credentials is issued when the worker reclaims the task.

clientIdstring[1:∞]

The clientId for the temporary credentials.

accessTokenstring[1:∞]

The accessToken for the temporary credentials.

certificatestring[1:∞]

The certificate for the temporary credentials, these are required for the temporary credentials to work.



Claim Task

Method
post
Route
/task/<taskId>/runs/<runId>/claim
Scopes
any of
all of
queue:claim-task:<provisionerId>/<workerType> and
queue:worker-id:<workerGroup>/<workerId>
or
all of
queue:claim-task and
assume:worker-type:<provisionerId>/<workerType> and
assume:worker-id:<workerGroup>/<workerId>
Signature
claimTask(taskId, runId, payload) : result
Stability
stable

claim a task, more to be added later...

Request Payload

Task Claim Request (source)

Request to claim (or reclaim) a task

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker claiming the task is a part of.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker within the given workerGroup

Response

Task Claim Response (source)

Response to a successful task claim

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.

runIdinteger[0:1000]

run-id assigned to this run of the task

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker-group within which this run started.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker executing this run.

takenUntilstringdate-time

Time at which the run expires and is resolved as exception, with reason claim-expired if the run haven't been reclaimed.

taskObject of

Definition of a task that can be scheduled

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a provisioner, that can supply specified workerType

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for a worker-type within a specific provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task, this can be an identifier for a user or a service like the "task-graph-scheduler". Along with the taskGroupId this is used to form the permission scope queue:assume:scheduler-id:<schedulerId>/<taskGroupId>, this scope is necessary to schedule a defined task, or rerun a task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId. Defaults to taskId if property isn't specified.

dependenciesArray of[0:100]

List of dependent tasks. These must either be completed or resolved before this task is scheduled. See requires for semantics.

Task Dependencystring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

The taskId of a task that must be resolved before this task is scheduled.

requiresstring
  • all-completed
  • all-resolved

The tasks relation to its dependencies. This property specifies the semantics of the task.dependencies property. If all-completed is given the task will be scheduled when all dependencies are resolved completed (successful resolution). If all-resolved is given the task will be scheduled when all dependencies have been resolved, regardless of what their resolution is.

routesArray of[0:64]

List of task specific routes, AMQP messages will be CC'ed to these routes.

Task Specific Routestring[1:249]

A task specific route, AMQP messages will be CC'ed with a routing key matching route.<task-specific route>. It's possible to dot (.) in the task specific route to make sub-keys, etc. See the RabbitMQ tutorial for examples on how to use routing-keys.

prioritystring
  • highest
  • very-high
  • high
  • medium
  • low
  • very-low
  • lowest

Priority of task, this defaults to lowest and the scope queue:create-task:<priority>/<provisionerId>/<workerType> is required to define a task with <priority>.

retriesinteger[0:49]

Number of times to retry the task in case of infrastructure issues. An infrastructure issue is a worker node that crashes or is shutdown, these events are to be expected.

createdstringdate-time

Creation time of task

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this. If this property isn't it will be set to deadline plus one year (this default may subject to change).

scopesArray of

List of scopes (or scope-patterns) that the task is authorized to use.

Scopestring^[\x20-\x7e]*$

A scope (or scope-patterns) which the task is authorized to use. This can be a string or a string ending with * which will authorize all scopes for which the string is a prefix. Scopes must be composed of printable ASCII characters and spaces.

payloadObject of

Task-specific payload following worker-specific format. For example the docker-worker requires keys like: image, commands and features. Refer to the documentation of docker-worker for details.

Anything ¯\_(ツ)_/¯
metadataObject of

Required task metadata

namestring[0:255]

Human readable name of task, used to very briefly given an idea about what the task does.

descriptionstring[0:32768]

Human readable description of the task, please explain what the task does. A few lines of documentation is not going to hurt you.

ownerstring[0:255]

E-mail of person who caused this task, e.g. the person who did hg push. The person we should contact to ask why this task is here.

sourcestring[0:4096]^https?://

Link to source of this task, should specify a file, revision and repository. This should be place someone can go an do a git/hg blame to who came up with recipe for this task.

tagsObject of

Arbitrary key-value tags (only strings limited to 4k). These can be used to attach informal metadata to a task. Use this for informal tags that tasks can be classified by. You can also think of strings here as candidates for formal metadata. Something like purpose: 'build' || 'test' is a good example.

<string>string[0:4096]
extraObject of
default: [object Object]

Object with properties that can hold any kind of extra data that should be associated with the task. This can be data for the task which doesn't fit into payload, or it can supplementary data for use in services listening for events from this task. For example this could be details to display on treeherder, or information for indexing the task. Please, try to put all related information under one property, so extra data keys for treeherder reporting and task indexing don't conflict, hence, we have reusable services. Warning, do not stuff large data-sets in here, task definitions should not take-up multiple MiBs.

Anything ¯\_(ツ)_/¯
credentialsObject of

Temporary credentials granting task.scopes and the scope: queue:claim-task:<taskId>/<runId> which allows the worker to reclaim the task, upload artifacts and report task resolution.

The temporary credentials are set to expire after takenUntil. They won't expire exactly at takenUntil but shortly after, hence, requests coming close takenUntil won't have problems even if there is a little clock drift.

Workers should use these credentials when making requests on behalf of a task. This includes requests to create artifacts, reclaiming the task reporting the task completed, failed or exception.

Note, a new set of temporary credentials is issued when the worker reclaims the task.

clientIdstring[1:∞]

The clientId for the temporary credentials.

accessTokenstring[1:∞]

The accessToken for the temporary credentials.

certificatestring[1:∞]

The certificate for the temporary credentials, these are required for the temporary credentials to work.



Reclaim task

Method
post
Route
/task/<taskId>/runs/<runId>/reclaim
Scopes
any of
queue:reclaim-task:<taskId>/<runId> or
all of
queue:claim-task and
assume:worker-id:<workerGroup>/<workerId>
Signature
reclaimTask(taskId, runId) : result
Stability
stable

Refresh the claim for a specific runId for given taskId. This updates the takenUntil property and returns a new set of temporary credentials for performing requests on behalf of the task. These credentials should be used in-place of the credentials returned by claimWork.

The reclaimTask requests serves to:

  • Postpone takenUntil preventing the queue from resolving claim-expired,
  • Refresh temporary credentials used for processing the task, and
  • Abort execution if the task/run have been resolved.

If the takenUntil timestamp is exceeded the queue will resolve the run as exception with reason claim-expired, and proceeded to retry to the task. This ensures that tasks are retried, even if workers disappear without warning.

If the task is resolved, this end-point will return 409 reporting RequestConflict. This typically happens if the task have been canceled or the task.deadline have been exceeded. If reclaiming fails, workers should abort the task and forget about the given runId. There is no need to resolve the run or upload artifacts.

Response

Task Reclaim Response (source)

Response to a successful task claim

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.

runIdinteger[0:1000]

run-id assigned to this run of the task

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker-group within which this run started.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker executing this run.

takenUntilstringdate-time

Time at which the run expires and is resolved as exception, with reason claim-expired if the run haven't been reclaimed.

credentialsObject of

Temporary credentials granting task.scopes and the scope: queue:claim-task:<taskId>/<runId> which allows the worker to reclaim the task, upload artifacts and report task resolution.

The temporary credentials are set to expire after takenUntil. They won't expire exactly at takenUntil but shortly after, hence, requests coming close takenUntil won't have problems even if there is a little clock drift.

Workers should use these credentials when making requests on behalf of a task. This includes requests to create artifacts, reclaiming the task reporting the task completed, failed or exception.

Note, a new set of temporary credentials is issued when the worker reclaims the task.

clientIdstring[1:∞]

The clientId for the temporary credentials.

accessTokenstring[1:∞]

The accessToken for the temporary credentials.

certificatestring[1:∞]

The certificate for the temporary credentials, these are required for the temporary credentials to work.



Report Run Completed

Method
post
Route
/task/<taskId>/runs/<runId>/completed
Scopes
any of
queue:resolve-task:<taskId>/<runId> or
all of
queue:resolve-task and
assume:worker-id:<workerGroup>/<workerId>
Signature
reportCompleted(taskId, runId) : result
Stability
stable

Report a task completed, resolving the run as completed.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Report Run Failed

Method
post
Route
/task/<taskId>/runs/<runId>/failed
Scopes
any of
queue:resolve-task:<taskId>/<runId> or
all of
queue:resolve-task and
assume:worker-id:<workerGroup>/<workerId>
Signature
reportFailed(taskId, runId) : result
Stability
stable

Report a run failed, resolving the run as failed. Use this to resolve a run that failed because the task specific code behaved unexpectedly. For example the task exited non-zero, or didn't produce expected output.

Do not use this if the task couldn't be run because if malformed payload, or other unexpected condition. In these cases we have a task exception, which should be reported with reportException.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Report Task Exception

Method
post
Route
/task/<taskId>/runs/<runId>/exception
Scopes
any of
queue:resolve-task:<taskId>/<runId> or
all of
queue:resolve-task and
assume:worker-id:<workerGroup>/<workerId>
Signature
reportException(taskId, runId, payload) : result
Stability
stable

Resolve a run as exception. Generally, you will want to report tasks as failed instead of exception. You should reportException if,

  • The task.payload is invalid,
  • Non-existent resources are referenced,
  • Declared actions cannot be executed due to unavailable resources,
  • The worker had to shutdown prematurely,
  • The worker experienced an unknown error, or,
  • The task explicitly requested a retry.

Do not use this to signal that some user-specified code crashed for any reason specific to this code. If user-specific code hits a resource that is temporarily unavailable worker should report task failed.

Request Payload

Task Exception Request (source)

Request for a run of a task to be resolved with an exception

reasonstring
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • superseded
  • intermittent-task

Reason that the task is resolved with an exception. This is a subset of the values for resolvedReason given in the task status structure. Report worker-shutdown if the run failed because the worker had to shutdown (spot node disappearing). In case of worker-shutdown the queue will immediately retry the task, by making a new run. This is much faster than ignoreing the issue and letting the task retry by claim expiration. For any other reason reported the queue will not retry the task. Report malformed-payload if the task.payload doesn't match the schema for the worker payload, or referenced resource doesn't exists. In either case, you should still log the error to a log file for the specific run. Report resource-unavailable if a resource/service needed or referenced in task.payload is temporarily unavailable. Do not use this unless you know the resource exists, if the resource doesn't exist you should report malformed-payload. Example use-case if you contact the index (a service) on behalf of the task, because of a declaration in task.payload, and the service (index) is temporarily down. Don't use this if a URL returns 404, but if it returns 503 or hits a timeout when you retry the request, then this may be a valid exception. The queue assumes that workers have applied retries as needed, and will not retry the task. Report internal-error if the worker experienced an unhandled internal error from which it couldn't recover. The queue will not retry runs resolved with this reason, but you are clearly signaling that this is a bug in the worker code. Report superseded if the task was determined to have been superseded by another task, and its results are no longer needed. It is convention in this case to create an artifact entitled public/superseded-by containing the taskId of the task that superseded this one. Report intermittent-task if the task explicitly requested a retry because task is intermittent. Workers can choose whether or not to support this, but workers shouldn't blindly report this for every task that fails.

Response

Task Status Response (source)

Response to a task status request

statusObject of

A representation of task status as known by the queue

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner that this task must be scheduled on

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

schedulerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the scheduler that defined this task.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Identifier for a group of tasks scheduled together with this task, by scheduler identified by schedulerId. For tasks scheduled by the task-graph scheduler, this is the taskGraphId.

deadlinestringdate-time

Deadline of the task, pending and running runs are resolved as exception if not resolved by other means before the deadline. Note, deadline cannot be more than 5 days into the future

expiresstringdate-time

Task expiration, time at which task definition and status is deleted. Notice that all artifacts for the task must have an expiration that is no later than this.

retriesLeftinteger[0:999]

Number of retries left for the task in case of infrastructure issues

statestring
  • unscheduled
  • pending
  • running
  • completed
  • failed
  • exception

State of this task. This is just an auxiliary property derived from state of latests run, or unscheduled if none.

runsArray of

List of runs, ordered so that index i has runId == i

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

statestring
  • pending
  • running
  • completed
  • failed
  • exception

State of this run

reasonCreatedstring
  • scheduled
  • retry
  • task-retry
  • rerun
  • exception

Reason for the creation of this run, more reasons may be added in the future.

reasonResolvedstring
  • completed
  • failed
  • deadline-exceeded
  • canceled
  • superseded
  • claim-expired
  • worker-shutdown
  • malformed-payload
  • resource-unavailable
  • internal-error
  • intermittent-task

Reason that run was resolved, this is mainly useful for runs resolved as exception. Note, more reasons may be added in the future, also this property is only available after the run is resolved. Some of these reasons, notably intermittent-task, worker-shutdown, and claim-expired, will trigger an automatic retry of the task.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing. Note, this property is only present after the run is claimed.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup. Note, this property is only available after the run has been claimed.

takenUntilstringdate-time

Time at which the run expires and is resolved as failed, if the run isn't reclaimed. Note, only present after the run has been claimed.

scheduledstringdate-time

Date-time at which this run was scheduled, ie. when the run was created in state pending.

startedstringdate-time

Date-time at which this run was claimed, ie. when the run changed state from pending to running. This property is only present after the run has been claimed.

resolvedstringdate-time

Date-time at which this run was resolved, ie. when the run changed state from running to either completed, failed or exception. This property is only present after the run as been resolved.



Create Artifact

Method
post
Route
/task/<taskId>/runs/<runId>/artifacts/<name>
Scopes
any of
queue:create-artifact:<taskId>/<runId> or
all of
queue:create-artifact:<name> and
assume:worker-id:<workerGroup>/<workerId>
Signature
createArtifact(taskId, runId, name, payload) : result
Stability
stable

This API end-point creates an artifact for a specific run of a task. This should only be used by a worker currently operating on this task, or from a process running within the task (ie. on the worker).

All artifacts must specify when they expires, the queue will automatically take care of deleting artifacts past their expiration point. This features makes it feasible to upload large intermediate artifacts from data processing applications, as the artifacts can be set to expire a few days later.

We currently support 3 different storageTypes, each storage type have slightly different features and in some cases difference semantics. We also have 2 deprecated storageTypes which are only maintained for backwards compatiability and should not be used in new implementations

Blob artifacts, are useful for storing large files. Currently, these are all stored in S3 but there are facilities for adding support for other backends in futre. A call for this type of artifact must provide information about the file which will be uploaded. This includes sha256 sums and sizes. This method will return a list of general form HTTP requests which are signed by AWS S3 credentials managed by the Queue. Once these requests are completed the list of ETag values returned by the requests must be passed to the queue completeArtifact method

S3 artifacts, DEPRECATED is useful for static files which will be stored on S3. When creating an S3 artifact the queue will return a pre-signed URL to which you can do a PUT request to upload your artifact. Note that PUT request must specify the content-length header and must give the content-type header the same value as in the request to createArtifact.

Azure artifacts, DEPRECATED are stored in Azure Blob Storage service which given the consistency guarantees and API interface offered by Azure is more suitable for artifacts that will be modified during the execution of the task. For example docker-worker has a feature that persists the task log to Azure Blob Storage every few seconds creating a somewhat live log. A request to create an Azure artifact will return a URL featuring a Shared-Access-Signature, refer to MSDN for further information on how to use these. Warning: azure artifact is currently an experimental feature subject to changes and data-drops.

Reference artifacts, only consists of meta-data which the queue will store for you. These artifacts really only have a url property and when the artifact is requested the client will be redirect the URL provided with a 303 (See Other) redirect. Please note that we cannot delete artifacts you upload to other service, we can only delete the reference to the artifact, when it expires.

Error artifacts, only consists of meta-data which the queue will store for you. These artifacts are only meant to indicate that you the worker or the task failed to generate a specific artifact, that you would otherwise have uploaded. For example docker-worker will upload an error artifact, if the file it was supposed to upload doesn't exists or turns out to be a directory. Clients requesting an error artifact will get a 403 (Forbidden) response. This is mainly designed to ensure that dependent tasks can distinguish between artifacts that were suppose to be generated and artifacts for which the name is misspelled.

Artifact immutability, generally speaking you cannot overwrite an artifact when created. But if you repeat the request with the same properties the request will succeed as the operation is idempotent. This is useful if you need to refresh a signed URL while uploading. Do not abuse this to overwrite artifacts created by another entity! Such as worker-host overwriting artifact created by worker-code.

As a special case the url property on reference artifacts can be updated. You should only use this to update the url property for reference artifacts your process has created.

Request Payload

Post Artifact Request (source)

Request a authorization to put and artifact or posting of a URL as an artifact. Note that the storageType property is referenced in the response as well.

Post Artifact RequestOne of

Request a authorization to put and artifact or posting of a URL as an artifact. Note that the storageType property is referenced in the response as well.

Blob Artifact RequestObject of

Request a list of requests in a generalized format which can be run to upload an artifact to storage managed by the queue.

storageTypestring
  • blob

Artifact storage type, in this case 'blob'

expiresstringdate-time

Date-time after which the artifact should be deleted. Note, that these will be collected over time, and artifacts may remain available after expiration. S3 based artifacts are identified in azure table storage and explicitly deleted on S3 after expiration.

contentTypestring[0:255]

Artifact mime-type, when uploading artifact to the signed PUT URL returned from this request this must given with the ContentType header. Please, provide correct mime-type, this make tooling a lot easier, specifically, always using application/json for JSON artifacts.

contentEncodingstring[0:255]

Optionally provide an encoding type which should be set as the HTTP Content-Encoding header for this artifact.

contentSha256string^[a-fA-F0-9]{64}$

The complete SHA256 value of the entire artifact. This must be the SHA256 of the file which is to be uploaded. For single part uploads, the upload will fail if the SHA256 value of what is uploaded does not match this value

contentLengthinteger

The number of bytes of the entire artifact. This must be the number of bytes in the file to be uploaded. For single part uploads, the upload will fail if the number of bytes uploaded does not match this value. A single part upload (e.g. no parts list) may be at most 5GB. This limit is enforced in the code because it is not possible to represent all of the restrictions in a json-schema. A multipart upload may be at most 5TB, with each part other than the last being between 5MB and 5GB in size.

transferSha256string^[a-fA-F0-9]{64}$

This is the sha256 of the bytes transfered across the wire to the backing datastore. If specified, it represents the post-content-encoding sha256 value

transferLengthinteger

The number of bytes transfered across the wire to the backing datastore. If specified, it represents the post-content-encoding byte count

partsArray of[1:∞]

A list of parts for a multipart upload. The presence of this list is how a multipart upload is differentiated from a single part upload. The items in this list represent individual parts for upload. For a multipart upload, the sha256 values provided here must match the sha256 value that S3 internally computes for the upload to be considered a success. The overall sha256 value is not checked explicitly because the S3 API does not allow for that, but the same code that is responsible for generating the parts hashes would also be generating the overall hash, which makes this less of a concern. The worst case is that we have artifacts which incorrectly do not validate, which is not as big of a security concern.

sha256string[64:64]^[a-fA-F0-9]{64}$

The sha256 hash of the part.

sizeinteger

The number of bytes in this part. Keep in mind for S3 that all but the last part must be minimum 5MB and the maximum for a single part is 5GB. The overall size may not exceed 5TB

S3 Artifact RequestObject of

Request for a signed PUT URL that will allow you to upload an artifact to an S3 bucket managed by the queue.

storageTypestring
  • s3

Artifact storage type, in this case 's3'

expiresstringdate-time

Date-time after which the artifact should be deleted. Note, that these will be collected over time, and artifacts may remain available after expiration. S3 based artifacts are identified in azure table storage and explicitly deleted on S3 after expiration.

contentTypestring[0:255]

Artifact mime-type, when uploading artifact to the signed PUT URL returned from this request this must given with the ContentType header. Please, provide correct mime-type, this make tooling a lot easier, specifically, always using application/json for JSON artifacts.

Azure Artifact RequestObject of

Request for an Azure Shared Access Signature (SAS) that will allow you to upload an artifact to an Azure blob storage container managed by the queue.

storageTypestring
  • azure

Artifact storage type, in this case azure

expiresstringdate-time

Date-time after which the artifact should be deleted. Note, that these will be collected over time, and artifacts may remain available after expiration. Azure based artifacts are identified in azure table storage and explicitly deleted in the azure storage container after expiration.

contentTypestring[0:255]

Artifact mime-type, when uploading artifact please use the same Content-Type, consistently using the correct mime-type make tooling a lot easier, specifically, always using application/json for JSON artifacts.

Redirect Artifact RequestObject of

Request the queue to redirect to a URL for a given artifact. This allows you to reference artifacts that aren't managed by the queue. The queue will still authenticate the request, so depending on the level of secrecy required, secret URLs might work. Note, this is mainly useful for public artifacts, for example temporary files directly stored on the worker host and only available there for a specific amount of time.

storageTypestring
  • reference

Artifact storage type, in this case reference

expiresstringdate-time

Date-time after which the queue should no longer redirect to this URL. Note, that the queue will and cannot delete the resource your URL references, you are responsible for doing that yourself.

contentTypestring[0:255]

Artifact mime-type for the resource to which the queue should redirect. Please use the same Content-Type, consistently using the correct mime-type make tooling a lot easier, specifically, always using application/json for JSON artifacts.

urlstringuri

URL to which the queue should redirect using a 303 (See other) redirect.

Error Artifact RequestObject of

Request the queue to reply 403 (forbidden) with reason and message to any GET request for this artifact. This is mainly useful as a way for a task to declare that it failed to provide an artifact it wanted to upload.

storageTypestring
  • error

Artifact storage type, in this case error

expiresstringdate-time

Date-time after which the queue should stop replying with the error and forget about the artifact.

reasonstring
  • file-missing-on-worker
  • invalid-resource-on-worker
  • too-large-file-on-worker

Reason why the artifact doesn't exist.

messagestring[0:4096]

Human readable explanation of why the artifact is missing

Response

Post Artifact Response (source)

Response to a request for posting an artifact. Note that the storageType property is referenced in the request as well.

Post Artifact ResponseOne of

Response to a request for posting an artifact. Note that the storageType property is referenced in the request as well.

Blob Artifact Response

Response to a request for creating a new blob artifact

S3 Artifact ResponseObject of

Response to a request for a signed PUT URL that will allow you to upload an artifact to an S3 bucket managed by the queue.

storageTypestring
  • s3

Artifact storage type, in this case 's3'

putUrlstringuri

URL to which a PUT request can be made to upload the artifact requested. Note, the Content-Length must be specified correctly, and the ContentType header must be set the value specified below.

expiresstringdate-time

Date-time after which the signed putUrl no longer works

contentTypestring[0:255]

Artifact mime-type, must be specified as header when uploading with the signed putUrl.

Azure Artifact ResponseObject of

Response to a request for an Azure Shared Access Signature (SAS) that will allow you to upload an artifact to an Azure blob storage container managed by the queue.

storageTypestring
  • azure

Artifact storage type, in this case azure

expiresstringdate-time

Date-time after which Shared Access Signature (SAS) will seize to work.

contentTypestring[0:255]

Artifact mime-type, should be specified with the x-ms-blob-content-type when committing the block.

putUrlstringuri

Shared Access Signature (SAS) with write permissions, see [Azure REST API] (http://msdn.microsoft.com/en-US/library/azure/dn140256.aspx) reference for details on how to use this.

Redirect Artifact ResponseObject of

Response to a request for the queue to redirect to a URL for a given artifact.

storageTypestring
  • reference

Artifact storage type, in this case reference

Error Artifact ResponseObject of

Response to a request for the queue to reply 403 (forbidden) with reason and message to any GET request for this artifact.

storageTypestring
  • error

Artifact storage type, in this case error



Complete Artifact

(experimental)

Method
put
Route
/task/<taskId>/runs/<runId>/artifacts/<name>
Scopes
any of
queue:create-artifact:<taskId>/<runId> or
all of
queue:create-artifact:<name> and
assume:worker-id:<workerGroup>/<workerId>
Signature
completeArtifact(taskId, runId, name, payload) : void
Stability
experimental

This endpoint finalises an upload done through the blob storageType. The queue will ensure that the task/run is still allowing artifacts to be uploaded. For single-part S3 blob artifacts, this endpoint will simply ensure the artifact is present in S3. For multipart S3 artifacts, the endpoint will perform the commit step of the multipart upload flow. As the final step for both multi and single part artifacts, the present entity field will be set to true to reflect that the artifact is now present and a message published to pulse. NOTE: This endpoint must be called for all artifacts of storageType 'blob'

Request Payload

Complete Artifact Request (source)

Complete an aritifact

etagsArray of

A list of the etags given by the API of the blob storage provider. This is an opaque string value provided by the API.

string


Get Artifact from Run

Method
get
Route
/task/<taskId>/runs/<runId>/artifacts/<name>
Scopes
if  private
all of
queue:get-artifact:<name>
Signature
getArtifact(taskId, runId, name) : void
Stability
stable

Get artifact by <name> from a specific run.

Public Artifacts, in-order to get an artifact you need the scope queue:get-artifact:<name>, where <name> is the name of the artifact. But if the artifact name starts with public/, authentication and authorization is not necessary to fetch the artifact.

API Clients, this method will redirect you to the artifact, if it is stored externally. Either way, the response may not be JSON. So API client users might want to generate a signed URL for this end-point and use that URL with an HTTP client that can handle responses correctly.

Downloading artifacts There are some special considerations for those http clients which download artifacts. This api endpoint is designed to be compatible with an HTTP 1.1 compliant client, but has extra features to ensure the download is valid. It is strongly recommend that consumers use either taskcluster-lib-artifact (JS), taskcluster-lib-artifact-go (Go) or the CLI written in Go to interact with artifacts.

In order to download an artifact the following must be done:

  1. Obtain queue url. Building a signed url with a taskcluster client is recommended
  2. Make a GET request which does not follow redirects
  3. In all cases, if specified, the x-taskcluster-location-{content,transfer}-{sha256,length} values must be validated to be equal to the Content-Length and Sha256 checksum of the final artifact downloaded. as well as any intermediate redirects
  4. If this response is a 500-series error, retry using an exponential backoff. No more than 5 retries should be attempted
  5. If this response is a 400-series error, treat it appropriately for your context. This might be an error in responding to this request or an Error storage type body. This request should not be retried.
  6. If this response is a 200-series response, the response body is the artifact. If the x-taskcluster-location-{content,transfer}-{sha256,length} and x-taskcluster-location-content-encoding are specified, they should match this response body
  7. If the response type is a 300-series redirect, the artifact will be at the location specified by the Location header. There are multiple artifact storage types which use a 300-series redirect.
  8. For all redirects followed, the user must verify that the content-sha256, content-length, transfer-sha256, transfer-length and content-encoding match every further request. The final artifact must also be validated against the values specified in the original queue response
  9. Caching of requests with an x-taskcluster-artifact-storage-type value of reference must not occur
  10. A request which has x-taskcluster-artifact-storage-type value of blob and does not have x-taskcluster-location-content-sha256 or x-taskcluster-location-content-length must be treated as an error

Headers The following important headers are set on the response to this method:

  • location: the url of the artifact if a redirect is to be performed
  • x-taskcluster-artifact-storage-type: the storage type. Example: blob, s3, error

The following important headers are set on responses to this method for Blob artifacts

  • x-taskcluster-location-content-sha256: the SHA256 of the artifact after any content-encoding is undone. Sha256 is hex encoded (e.g. [0-9A-Fa-f]{64})
  • x-taskcluster-location-content-length: the number of bytes after any content-encoding is undone
  • x-taskcluster-location-transfer-sha256: the SHA256 of the artifact before any content-encoding is undone. This is the SHA256 of what is sent over the wire. Sha256 is hex encoded (e.g. [0-9A-Fa-f]{64})
  • x-taskcluster-location-transfer-length: the number of bytes after any content-encoding is undone
  • x-taskcluster-location-content-encoding: the content-encoding used. It will either be gzip or identity right now. This is hardcoded to a value set when the artifact was created and no content-negotiation occurs
  • x-taskcluster-location-content-type: the content-type of the artifact

Caching, artifacts may be cached in data centers closer to the workers in-order to reduce bandwidth costs. This can lead to longer response times. Caching can be skipped by setting the header x-taskcluster-skip-cache: true, this should only be used for resources where request volume is known to be low, and caching not useful. (This feature may be disabled in the future, use is sparingly!)



Get Artifact from Latest Run

Method
get
Route
/task/<taskId>/artifacts/<name>
Scopes
if  private
all of
queue:get-artifact:<name>
Signature
getLatestArtifact(taskId, name) : void
Stability
stable

Get artifact by <name> from the last run of a task.

Public Artifacts, in-order to get an artifact you need the scope queue:get-artifact:<name>, where <name> is the name of the artifact. But if the artifact name starts with public/, authentication and authorization is not necessary to fetch the artifact.

API Clients, this method will redirect you to the artifact, if it is stored externally. Either way, the response may not be JSON. So API client users might want to generate a signed URL for this end-point and use that URL with a normal HTTP client.

Remark, this end-point is slightly slower than queue.getArtifact, so consider that if you already know the runId of the latest run. Otherwise, just us the most convenient API end-point.



Get Artifacts from Run

(experimental)

Method
get
Route
/task/<taskId>/runs/<runId>/artifacts
Signature
listArtifacts(taskId, runId, {continuationToken, limit}) : result
Stability
experimental

Returns a list of artifacts and associated meta-data for a given run.

As a task may have many artifacts paging may be necessary. If this end-point returns a continuationToken, you should call the end-point again with the continuationToken as the query-string option: continuationToken.

By default this end-point will list up-to 1000 artifacts in a single page you may limit this with the query-string parameter limit.

Response

List Artifacts Response (source)

List of artifacts for a given taskId and runId.

artifactsArray of

List of artifacts for given taskId and runId.

storageTypestring
  • blob
  • s3
  • azure
  • reference
  • error

This is the storageType for the request that was used to create the artifact.

namestring[0:1024]

Name of the artifact that was created, this is useful if you want to attempt to fetch the artifact.

expiresstringdate-time

Date and time after which the artifact created will be automatically deleted by the queue.

contentTypestring[0:255]

Mimetype for the artifact that was created.

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of artifacts. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called with continuationToken until you get a result without a continuationToken.



Get Artifacts from Latest Run

(experimental)

Method
get
Route
/task/<taskId>/artifacts
Signature
listLatestArtifacts(taskId, {continuationToken, limit}) : result
Stability
experimental

Returns a list of artifacts and associated meta-data for the latest run from the given task.

As a task may have many artifacts paging may be necessary. If this end-point returns a continuationToken, you should call the end-point again with the continuationToken as the query-string option: continuationToken.

By default this end-point will list up-to 1000 artifacts in a single page you may limit this with the query-string parameter limit.

Response

List Artifacts Response (source)

List of artifacts for a given taskId and runId.

artifactsArray of

List of artifacts for given taskId and runId.

storageTypestring
  • blob
  • s3
  • azure
  • reference
  • error

This is the storageType for the request that was used to create the artifact.

namestring[0:1024]

Name of the artifact that was created, this is useful if you want to attempt to fetch the artifact.

expiresstringdate-time

Date and time after which the artifact created will be automatically deleted by the queue.

contentTypestring[0:255]

Mimetype for the artifact that was created.

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of artifacts. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called with continuationToken until you get a result without a continuationToken.



Get a list of all active provisioners

(experimental)

Method
get
Route
/provisioners
Signature
listProvisioners({continuationToken, limit}) : result
Stability
experimental

Get all active provisioners.

The term "provisioner" is taken broadly to mean anything with a provisionerId. This does not necessarily mean there is an associated service performing any provisioning activity.

The response is paged. If this end-point returns a continuationToken, you should call the end-point again with the continuationToken as a query-string option. By default this end-point will list up to 1000 provisioners in a single page. You may limit this with the query-string parameter limit.

Response

List Provisioners Response (source)

provisionersArray of
provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the provisioner. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the provisioner.

expiresstringdate-time

Date and time after which the provisioner created will be automatically deleted by the queue.

lastDateActivestringdate-time

Date and time where the provisioner was last seen active

actionsArray of

See taskcluster actions documentation.

namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • provisioner
  • worker-type
  • worker

Actions have a "context" that is one of provisioner, worker-type, or worker, indicating which it applies to. context is used by the front-end to know where to display the action.

context Page displayed
provisioner Provisioner Explorer
worker-type Workers Explorer
worker Worker Explorer
urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of provisioners. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called with continuationToken until you get a result without a continuationToken.



Get an active provisioner

(experimental)

Method
get
Route
/provisioners/<provisionerId>
Signature
getProvisioner(provisionerId) : result
Stability
experimental

Get an active provisioner.

The term "provisioner" is taken broadly to mean anything with a provisionerId. This does not necessarily mean there is an associated service performing any provisioning activity.

Response

Provisioner Response (source)

Response containing information about a provisioner.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the provisioner. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the provisioner.

expiresstringdate-time

Date and time after which the provisioner will be automatically deleted by the queue.

lastDateActivestringdate-time

Date of the last time this provisioner was seen active. lastDateActive is updated every 6 hours but may be off by up-to 6 hours. Nonetheless, lastDateActive is a good indicator of when the provisioner was last seen active.

actionsArray of

See taskcluster actions documentation.

namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • provisioner
  • worker-type
  • worker

Actions have a "context" that is one of provisioner, worker-type, or worker, indicating which it applies to. context is used by the front-end to know where to display the action.

context Page displayed
provisioner Provisioner Explorer
worker-type Workers Explorer
worker Worker Explorer
urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Update a provisioner

(experimental)

Method
put
Route
/provisioners/<provisionerId>
Scopes
all of
for each  property in  properties
queue:declare-provisioner:<provisionerId>#<property>
Signature
declareProvisioner(provisionerId, payload) : result
Stability
experimental

Declare a provisioner, supplying some details about it.

declareProvisioner allows updating one or more properties of a provisioner as long as the required scopes are possessed. For example, a request to update the aws-provisioner-v1 provisioner with a body {description: 'This provisioner is great'} would require you to have the scope queue:declare-provisioner:aws-provisioner-v1#description.

The term "provisioner" is taken broadly to mean anything with a provisionerId. This does not necessarily mean there is an associated service performing any provisioning activity.

Request Payload

Provisioner Request (source)

Request to update a provisioner.

stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the provisioner. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the provisioner.

expiresstringdate-time

Date and time after which the provisioner will be automatically deleted by the queue.

actionsArray of

See taskcluster actions documentation.

namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • provisioner
  • worker-type
  • worker

Actions have a "context" that is one of provisioner, worker-type, or worker, indicating which it applies to. context is used by the front-end to know where to display the action.

context Page displayed
provisioner Provisioner Explorer
worker-type Workers Explorer
worker Worker Explorer
urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.

Response

Provisioner Response (source)

Response containing information about a provisioner.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the provisioner. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the provisioner.

expiresstringdate-time

Date and time after which the provisioner will be automatically deleted by the queue.

lastDateActivestringdate-time

Date of the last time this provisioner was seen active. lastDateActive is updated every 6 hours but may be off by up-to 6 hours. Nonetheless, lastDateActive is a good indicator of when the provisioner was last seen active.

actionsArray of

See taskcluster actions documentation.

namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • provisioner
  • worker-type
  • worker

Actions have a "context" that is one of provisioner, worker-type, or worker, indicating which it applies to. context is used by the front-end to know where to display the action.

context Page displayed
provisioner Provisioner Explorer
worker-type Workers Explorer
worker Worker Explorer
urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Get Number of Pending Tasks

Method
get
Route
/pending/<provisionerId>/<workerType>
Signature
pendingTasks(provisionerId, workerType) : result
Stability
stable

Get an approximate number of pending tasks for the given provisionerId and workerType.

The underlying Azure Storage Queues only promises to give us an estimate. Furthermore, we cache the result in memory for 20 seconds. So consumers should be no means expect this to be an accurate number. It is, however, a solid estimate of the number of pending tasks.

Response

Count Pending Tasks Response (source)

Response to a request for the number of pending tasks for a given provisionerId and workerType.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Unique identifier for the provisioner

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker type within the specified provisioner

pendingTasksinteger

An approximate number of pending tasks for the given provisionerId and workerType. This is based on Azure Queue Storage metadata API, thus, number of reported here may be higher than actual number of pending tasks. But there cannot be more pending tasks reported here. Ie. this is an upper-bound on the number of pending tasks.



Get a list of all active worker-types

(experimental)

Method
get
Route
/provisioners/<provisionerId>/worker-types
Signature
listWorkerTypes(provisionerId, {continuationToken, limit}) : result
Stability
experimental

Get all active worker-types for the given provisioner.

The response is paged. If this end-point returns a continuationToken, you should call the end-point again with the continuationToken as a query-string option. By default this end-point will list up to 1000 worker-types in a single page. You may limit this with the query-string parameter limit.

Response

List Worker-Types Response (source)

Response from a listWorkerTypes request.

workerTypesArray of

List of worker-types in this provisioner.

workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the worker-type. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the worker-type.

expiresstringdate-time

Date and time after which the worker-type will be automatically deleted by the queue.

lastDateActivestringdate-time

Date and time where the worker-type was last seen active

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of worker-types in the provisioner. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called listWorkerTypes with continuationToken until you get a result without a continuationToken.



Get a worker-type

(experimental)

Method
get
Route
/provisioners/<provisionerId>/worker-types/<workerType>
Signature
getWorkerType(provisionerId, workerType) : result
Stability
experimental

Get a worker-type from a provisioner.

Response

Worker-type Response (source)

Response to a worker-type request from a provisioner.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the worker-type. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the worker-type.

expiresstringdate-time

Date and time after which the worker-type will be automatically deleted by the queue.

lastDateActivestringdate-time

Date of the last time this worker-type was seen active. lastDateActive is updated every 6 hours but may be off by up-to 6 hours. Nonetheless, lastDateActive is a good indicator of when the worker-type was last seen active.

actionsArray of
namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • worker-type

Only actions with the context worker-type are included.

urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Update a worker-type

(experimental)

Method
put
Route
/provisioners/<provisionerId>/worker-types/<workerType>
Scopes
all of
for each  property in  properties
queue:declare-worker-type:<provisionerId>/<workerType>#<property>
Signature
declareWorkerType(provisionerId, workerType, payload) : result
Stability
experimental

Declare a workerType, supplying some details about it.

declareWorkerType allows updating one or more properties of a worker-type as long as the required scopes are possessed. For example, a request to update the gecko-b-1-w2008 worker-type within the aws-provisioner-v1 provisioner with a body {description: 'This worker type is great'} would require you to have the scope queue:declare-worker-type:aws-provisioner-v1/gecko-b-1-w2008#description.

Request Payload

Worker-type Request (source)

Request to update a worker-type.

stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the provisioner. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the provisioner.

expiresstringdate-time

Date and time after which the worker-type will be automatically deleted by the queue.

Response

Worker-type Response (source)

Response to a worker-type request from a provisioner.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

stabilitystring
  • experimental
  • stable
  • deprecated

This is the stability of the worker-type. Accepted values:

  • experimental
  • stable
  • deprecated
descriptionstring

Description of the worker-type.

expiresstringdate-time

Date and time after which the worker-type will be automatically deleted by the queue.

lastDateActivestringdate-time

Date of the last time this worker-type was seen active. lastDateActive is updated every 6 hours but may be off by up-to 6 hours. Nonetheless, lastDateActive is a good indicator of when the worker-type was last seen active.

actionsArray of
namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • worker-type

Only actions with the context worker-type are included.

urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Get a list of all active workers of a workerType

(experimental)

Method
get
Route
/provisioners/<provisionerId>/worker-types/<workerType>/workers
Signature
listWorkers(provisionerId, workerType, {continuationToken, limit, quarantined}) : result
Stability
experimental

Get a list of all active workers of a workerType.

listWorkers allows a response to be filtered by quarantined and non quarantined workers. To filter the query, you should call the end-point with quarantined as a query-string option with a true or false value.

The response is paged. If this end-point returns a continuationToken, you should call the end-point again with the continuationToken as a query-string option. By default this end-point will list up to 1000 workers in a single page. You may limit this with the query-string parameter limit.

Response

List Workers Response (source)

Response from a listWorkers request.

workersArray of

List of workers in this worker-type.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for the worker group containing this worker.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for this worker (unique within this worker group).

quarantineUntilstringdate-time

Quarantining a worker allows the machine to remain alive but not accept jobs. Once the quarantineUntil time has elapsed, the worker resumes accepting jobs. Note that a quarantine can be lifted by setting quarantineUntil to the present time (or somewhere in the past).

firstClaimstringdate-time

Date of the first time this worker claimed a task.

latestTaskObject of

The most recent claimed task

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

continuationTokenstring

Opaque continuationToken to be given as query-string option to get the next set of workers in the worker-type. This property is only present if another request is necessary to fetch all results. In practice the next request with a continuationToken may not return additional results, but it can. Thus, you can only be sure to have all the results if you've called listWorkerTypes with continuationToken until you get a result without a continuationToken.



Get a worker-type

(experimental)

Method
get
Route
/provisioners/<provisionerId>/worker-types/<workerType>/workers/<workerGroup>/<workerId>
Signature
getWorker(provisionerId, workerType, workerGroup, workerId) : result
Stability
experimental

Get a worker from a worker-type.

Response

Worker Response (source)

Response containing information about a worker.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup.

recentTasksArray of

List of 20 most recent tasks claimed by the worker.

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

expiresstringdate-time

Date and time after which the worker will be automatically deleted by the queue.

quarantineUntilstringdate-time

Quarantining a worker allows the machine to remain alive but not accept jobs. Once the quarantineUntil time has elapsed, the worker resumes accepting jobs. Note that a quarantine can be lifted by setting quarantineUntil to the present time (or somewhere in the past).

firstClaimstringdate-time

Date of the first time this worker claimed a task.

actionsArray of
namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • worker

Only actions with the context worker are included.

urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Quarantine a worker

(experimental)

Method
put
Route
/provisioners/<provisionerId>/worker-types/<workerType>/workers/<workerGroup>/<workerId>
Scopes
all of
queue:quarantine-worker:<provisionerId>/<workerType>/<workerGroup>/<workerId>
Signature
quarantineWorker(provisionerId, workerType, workerGroup, workerId, payload) : result
Stability
experimental

Quarantine a worker

Request Payload

Quarantine Worker Request (source)

Request to update a worker's quarantineUntil property.

quarantineUntilstringdate-time

Quarantining a worker allows the machine to remain alive but not accept jobs. Once the quarantineUntil time has elapsed, the worker resumes accepting jobs. Note that a quarantine can be lifted by setting quarantineUntil to the present time (or somewhere in the past).

Response

Worker Response (source)

Response containing information about a worker.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup.

recentTasksArray of

List of 20 most recent tasks claimed by the worker.

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

expiresstringdate-time

Date and time after which the worker will be automatically deleted by the queue.

quarantineUntilstringdate-time

Quarantining a worker allows the machine to remain alive but not accept jobs. Once the quarantineUntil time has elapsed, the worker resumes accepting jobs. Note that a quarantine can be lifted by setting quarantineUntil to the present time (or somewhere in the past).

firstClaimstringdate-time

Date of the first time this worker claimed a task.

actionsArray of
namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • worker

Only actions with the context worker are included.

urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Declare a worker

(experimental)

Method
put
Route
/provisioners/<provisionerId>/worker-types/<workerType>/<workerGroup>/<workerId>
Scopes
all of
for each  property in  properties
queue:declare-worker:<provisionerId>/<workerType>/<workerGroup>/<workerId>#<property>
Signature
declareWorker(provisionerId, workerType, workerGroup, workerId, payload) : result
Stability
experimental

Declare a worker, supplying some details about it.

declareWorker allows updating one or more properties of a worker as long as the required scopes are possessed.

Request Payload

Worker Request (source)

Request to update a worker.

expiresstringdate-time

Date and time after which the worker will be automatically deleted by the queue.

Response

Worker Response (source)

Response containing information about a worker.

provisionerIdstring[1:22]^([a-zA-Z0-9-_]*)$
workerTypestring[1:22]^([a-zA-Z0-9-_]*)$

WorkerType name.

workerGroupstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for group that worker who executes this run is a part of, this identifier is mainly used for efficient routing.

workerIdstring[1:22]^([a-zA-Z0-9-_]*)$

Identifier for worker evaluating this run within given workerGroup.

recentTasksArray of

List of 20 most recent tasks claimed by the worker.

taskIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Unique task identifier, this is UUID encoded as URL-safe base64 and stripped of = padding.

runIdinteger[0:1000]

Id of this task run, run-ids always starts from 0

expiresstringdate-time

Date and time after which the worker will be automatically deleted by the queue.

quarantineUntilstringdate-time

Quarantining a worker allows the machine to remain alive but not accept jobs. Once the quarantineUntil time has elapsed, the worker resumes accepting jobs. Note that a quarantine can be lifted by setting quarantineUntil to the present time (or somewhere in the past).

firstClaimstringdate-time

Date of the first time this worker claimed a task.

actionsArray of
namestring

Short names for things like logging/error messages.

title

Appropriate title for any sort of Modal prompt.

contextstring
  • worker

Only actions with the context worker are included.

urlstring

When an action is triggered, a request is made using the url and method. Depending on the context, the following parameters will be substituted in the url:

context Path parameters
provisioner
worker-type ,
worker , , ,

Note: The request needs to be signed with the user's Taskcluster credentials.

methodstring
  • POST
  • PUT
  • DELETE
  • PATCH

Method to indicate the desired action to be performed for a given resource.

descriptionstring

Description of the provisioner.



Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.