gecko-dev/third_party/python/taskcluster

Taskcluster Client Library in Python

This is a library used to interact with Taskcluster within Python programs. It presents the entire REST API to consumers as well as being able to generate URLs Signed by Hawk credentials. It can also generate routing keys for listening to pulse messages from Taskcluster.

The library builds the REST API methods from the same API Reference format as the Javascript client library.

Generating Temporary Credentials

If you have non-temporary taskcluster credentials you can generate a set of temporary credentials as follows. Notice that the credentials cannot last more than 31 days, and you can only revoke them by revoking the credentials that was used to issue them (this takes up to one hour).

It is not the responsibility of the caller to apply any clock drift adjustment to the start or expiry time - this is handled by the auth service directly.

import datetime

start = datetime.datetime.now()
expiry = start + datetime.timedelta(0,60)
scopes = ['ScopeA', 'ScopeB']
name = 'foo'

credentials = taskcluster.createTemporaryCredentials(
    # issuing clientId
    clientId,
    # issuing accessToken
    accessToken,
    # Validity of temporary credentials starts here, in timestamp
    start,
    # Expiration of temporary credentials, in timestamp
    expiry,
    # Scopes to grant the temporary credentials
    scopes,
    # credential name (optional)
    name
)

You cannot use temporary credentials to issue new temporary credentials. You must have auth:create-client:<name> to create a named temporary credential, but unnamed temporary credentials can be created regardless of your scopes.

API Documentation

The REST API methods are documented in the reference docs.

Query-String arguments

Query string arguments are now supported. In order to use them, you can call a method like this:

queue.listTaskGroup('JzTGxwxhQ76_Tt1dxkaG5g', query={'continuationToken': outcome.get('continuationToken')})

These query-string arguments are only supported using this calling convention

Sync vs Async

The objects under taskcluster (e.g., taskcluster.Queue) are python2-compatible and operate synchronously.

The objects under taskcluster.aio (e.g., taskcluster.aio.Queue) require python>=3.5. The async objects use asyncio coroutines for concurrency; this allows us to put I/O operations in the background, so operations that require the cpu can happen sooner. Given dozens of operations that can run concurrently (e.g., cancelling a medium-to-large task graph), this can result in significant performance improvements. The code would look something like

#!/usr/bin/env python
import aiohttp
import asyncio
from taskcluster.aio import Auth

async def do_ping():
    with aiohttp.ClientSession() as session:
        a = Auth(session=session)
        print(await a.ping())

loop = asyncio.get_event_loop()
loop.run_until_complete(do_ping())

Other async code examples are available here.

Here's a slide deck for an introduction to async python.

Usage

• Here's a simple command:

  import taskcluster
  index = taskcluster.Index({'credentials': {'clientId': 'id', 'accessToken': 'accessToken'}})
  index.ping()
  

• There are four calling conventions for methods:

  client.method(v1, v1, payload)
  client.method(payload, k1=v1, k2=v2)
  client.method(payload=payload, query=query, params={k1: v1, k2: v2})
  client.method(v1, v2, payload=payload, query=query)
  

• Options for the topic exchange methods can be in the form of either a single dictionary argument or keyword arguments. Only one form is allowed

  from taskcluster import client
  qEvt = client.QueueEvents()
  # The following calls are equivalent
  qEvt.taskCompleted({'taskId': 'atask'})
  qEvt.taskCompleted(taskId='atask')
  

Pagination

There are two ways to accomplish pagination easily with the python client. The first is to implement pagination in your code:

import taskcluster
queue = taskcluster.Queue()
i = 0
tasks = 0
outcome = queue.listTaskGroup('JzTGxwxhQ76_Tt1dxkaG5g')
while outcome.get('continuationToken'):
    print('Response %d gave us %d more tasks' % (i, len(outcome['tasks'])))
    if outcome.get('continuationToken'):
        outcome = queue.listTaskGroup('JzTGxwxhQ76_Tt1dxkaG5g', query={'continuationToken': outcome.get('continuationToken')})
    i += 1
    tasks += len(outcome.get('tasks', []))
print('Task Group %s has %d tasks' % (outcome['taskGroupId'], tasks))

There's also an experimental feature to support built in automatic pagination in the sync client. This feature allows passing a callback as the 'paginationHandler' keyword-argument. This function will be passed the response body of the API method as its sole positional arugment.

This example of the built in pagination shows how a list of tasks could be built and then counted:

import taskcluster
queue = taskcluster.Queue()

responses = []

def handle_page(y):
    print("%d tasks fetched" % len(y.get('tasks', [])))
    responses.append(y)

queue.listTaskGroup('JzTGxwxhQ76_Tt1dxkaG5g', paginationHandler=handle_page)

tasks = 0
for response in responses:
    tasks += len(response.get('tasks', []))

print("%d requests fetch %d tasks" % (len(responses), tasks))

Logging

Logging is set up in taskcluster/__init__.py. If the special DEBUG_TASKCLUSTER_CLIENT environment variable is set, the __init__.py module will set the logging module's level for its logger to logging.DEBUG and if there are no existing handlers, add a logging.StreamHandler() instance. This is meant to assist those who do not wish to bother figuring out how to configure the python logging module but do want debug messages

Scopes

The scopeMatch(assumedScopes, requiredScopeSets) function determines whether one or more of a set of required scopes are satisfied by the assumed scopes, taking *-expansion into account. This is useful for making local decisions on scope satisfaction, but note that assumed_scopes must be the expanded scopes, as this function cannot perform expansion.

It takes a list of a assumed scopes, and a list of required scope sets on disjunctive normal form, and checks if any of the required scope sets are satisfied.

Example:

    requiredScopeSets = [
        ["scopeA", "scopeB"],
        ["scopeC:*"]
    ]
    assert scopesMatch(['scopeA', 'scopeB'], requiredScopeSets)
    assert scopesMatch(['scopeC:xyz'], requiredScopeSets)
    assert not scopesMatch(['scopeA'], requiredScopeSets)
    assert not scopesMatch(['scopeC'], requiredScopeSets)

Relative Date-time Utilities

A lot of taskcluster APIs requires ISO 8601 time stamps offset into the future as way of providing expiration, deadlines, etc. These can be easily created using datetime.datetime.isoformat(), however, it can be rather error prone and tedious to offset datetime.datetime objects into the future. Therefore this library comes with two utility functions for this purposes.

dateObject = taskcluster.fromNow("2 days 3 hours 1 minute")
# datetime.datetime(2017, 1, 21, 17, 8, 1, 607929)
dateString = taskcluster.fromNowJSON("2 days 3 hours 1 minute")
# '2017-01-21T17:09:23.240178Z'

By default it will offset the date time into the future, if the offset strings are prefixed minus (-) the date object will be offset into the past. This is useful in some corner cases.

dateObject = taskcluster.fromNow("- 1 year 2 months 3 weeks 5 seconds");
# datetime.datetime(2015, 10, 30, 18, 16, 50, 931161)

The offset string is ignorant of whitespace and case insensitive. It may also optionally be prefixed plus + (if not prefixed minus), any + prefix will be ignored. However, entries in the offset string must be given in order from high to low, ie. 2 years 1 day. Additionally, various shorthands may be employed, as illustrated below.

  years,    year,   yr,   y
  months,   month,  mo
  weeks,    week,         w
  days,     day,          d
  hours,    hour,         h
  minutes,  minute, min
  seconds,  second, sec,  s

The fromNow method may also be given a date to be relative to as a second argument. This is useful if offset the task expiration relative to the the task deadline or doing something similar. This argument can also be passed as the kwarg dateObj

dateObject1 = taskcluster.fromNow("2 days 3 hours");
dateObject2 = taskcluster.fromNow("1 year", dateObject1);
taskcluster.fromNow("1 year", dateObj=dateObject1);
# datetime.datetime(2018, 1, 21, 17, 59, 0, 328934)

Methods contained in the client library

Methods in taskcluster.Auth

import asyncio # Only for async 
// Create Auth client instance
import taskcluster
import taskcluster.aio

auth = taskcluster.Auth(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncAuth = taskcluster.aio.Auth(options, session=session)

Authentication related API end-points for Taskcluster and related services. These API end-points are of interest if you wish to:

• Authorize a request signed with Taskcluster credentials,
• Manage clients and roles,
• Inspect or audit clients and roles,
• Gain access to various services guarded by this API.

Note that in this service "authentication" refers to validating the correctness of the supplied credentials (that the caller posesses the appropriate access token). This service does not provide any kind of user authentication (identifying a particular person).

Clients

The authentication service manages clients, at a high-level each client consists of a clientId, an accessToken, scopes, and some metadata. The clientId and accessToken can be used for authentication when calling Taskcluster APIs.

The client's scopes control the client's access to Taskcluster resources. The scopes are expanded by substituting roles, as defined below.

Roles

A role consists of a roleId, a set of scopes and a description. Each role constitutes a simple expansion rule that says if you have the scope: assume:<roleId> you get the set of scopes the role has. Think of the assume:<roleId> as a scope that allows a client to assume a role.

As in scopes the * kleene star also have special meaning if it is located at the end of a roleId. If you have a role with the following roleId: my-prefix*, then any client which has a scope staring with assume:my-prefix will be allowed to assume the role.

Guarded Services

The authentication service also has API end-points for delegating access to some guarded service such as AWS S3, or Azure Table Storage. Generally, we add API end-points to this server when we wish to use Taskcluster credentials to grant access to a third-party service used by many Taskcluster components.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
auth.ping() # -> None`
# Async call
await asyncAuth.ping() # -> None

List Clients

Get a list of all clients. With prefix, only clients for which it is a prefix of the clientId are returned.

By default this end-point will try to return up to 1000 clients in one request. But it may return less, even none. 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 listClients with the last continuationToken until you get a result without a continuationToken.

Required output schema

# Sync calls
auth.listClients() # -> result`
# Async call
await asyncAuth.listClients() # -> result

Get Client

Get information about a single client.

Takes the following arguments:

• clientId

Required output schema

# Sync calls
auth.client(clientId) # -> result`
auth.client(clientId='value') # -> result
# Async call
await asyncAuth.client(clientId) # -> result
await asyncAuth.client(clientId='value') # -> result

Create Client

Create a new client and get the accessToken for this client. You should store the accessToken from this API call as there is no other way to retrieve it.

If you loose the accessToken you can call resetAccessToken to reset it, and a new accessToken will be returned, but you cannot retrieve the current accessToken.

If a client with the same clientId already exists this operation will fail. Use updateClient if you wish to update an existing client.

The caller's scopes must satisfy scopes.

Takes the following arguments:

• clientId

Required input schema

Required output schema

# Sync calls
auth.createClient(clientId, payload) # -> result`
auth.createClient(payload, clientId='value') # -> result
# Async call
await asyncAuth.createClient(clientId, payload) # -> result
await asyncAuth.createClient(payload, clientId='value') # -> result

Reset accessToken

Reset a clients accessToken, this will revoke the existing accessToken, generate a new accessToken and return it from this call.

There is no way to retrieve an existing accessToken, so if you loose it you must reset the accessToken to acquire it again.

Takes the following arguments:

• clientId

Required output schema

# Sync calls
auth.resetAccessToken(clientId) # -> result`
auth.resetAccessToken(clientId='value') # -> result
# Async call
await asyncAuth.resetAccessToken(clientId) # -> result
await asyncAuth.resetAccessToken(clientId='value') # -> result

Update Client

Update an exisiting client. The clientId and accessToken cannot be updated, but scopes can be modified. The caller's scopes must satisfy all scopes being added to the client in the update operation. If no scopes are given in the request, the client's scopes remain unchanged

Takes the following arguments:

• clientId

Required input schema

Required output schema

# Sync calls
auth.updateClient(clientId, payload) # -> result`
auth.updateClient(payload, clientId='value') # -> result
# Async call
await asyncAuth.updateClient(clientId, payload) # -> result
await asyncAuth.updateClient(payload, clientId='value') # -> result

Enable Client

Enable a client that was disabled with disableClient. If the client is already enabled, this does nothing.

This is typically used by identity providers to re-enable clients that had been disabled when the corresponding identity's scopes changed.

Takes the following arguments:

• clientId

Required output schema

# Sync calls
auth.enableClient(clientId) # -> result`
auth.enableClient(clientId='value') # -> result
# Async call
await asyncAuth.enableClient(clientId) # -> result
await asyncAuth.enableClient(clientId='value') # -> result

Disable Client

Disable a client. If the client is already disabled, this does nothing.

This is typically used by identity providers to disable clients when the corresponding identity's scopes no longer satisfy the client's scopes.

Takes the following arguments:

• clientId

Required output schema

# Sync calls
auth.disableClient(clientId) # -> result`
auth.disableClient(clientId='value') # -> result
# Async call
await asyncAuth.disableClient(clientId) # -> result
await asyncAuth.disableClient(clientId='value') # -> result

Delete Client

Delete a client, please note that any roles related to this client must be deleted independently.

Takes the following arguments:

• clientId

# Sync calls
auth.deleteClient(clientId) # -> None`
auth.deleteClient(clientId='value') # -> None
# Async call
await asyncAuth.deleteClient(clientId) # -> None
await asyncAuth.deleteClient(clientId='value') # -> None

List Roles

Get a list of all roles, each role object also includes the list of scopes it expands to.

Required output schema

# Sync calls
auth.listRoles() # -> result`
# Async call
await asyncAuth.listRoles() # -> result

Get Role

Get information about a single role, including the set of scopes that the role expands to.

Takes the following arguments:

• roleId

Required output schema

# Sync calls
auth.role(roleId) # -> result`
auth.role(roleId='value') # -> result
# Async call
await asyncAuth.role(roleId) # -> result
await asyncAuth.role(roleId='value') # -> result

Create Role

Create a new role.

The caller's scopes must satisfy the new role's scopes.

If there already exists a role with the same roleId this operation will fail. Use updateRole to modify an existing role.

Creation of a role that will generate an infinite expansion will result in an error response.

Takes the following arguments:

• roleId

Required input schema

Required output schema

# Sync calls
auth.createRole(roleId, payload) # -> result`
auth.createRole(payload, roleId='value') # -> result
# Async call
await asyncAuth.createRole(roleId, payload) # -> result
await asyncAuth.createRole(payload, roleId='value') # -> result

Update Role

Update an existing role.

The caller's scopes must satisfy all of the new scopes being added, but need not satisfy all of the client's existing scopes.

An update of a role that will generate an infinite expansion will result in an error response.

Takes the following arguments:

• roleId

Required input schema

Required output schema

# Sync calls
auth.updateRole(roleId, payload) # -> result`
auth.updateRole(payload, roleId='value') # -> result
# Async call
await asyncAuth.updateRole(roleId, payload) # -> result
await asyncAuth.updateRole(payload, roleId='value') # -> result

Delete Role

Delete a role. This operation will succeed regardless of whether or not the role exists.

Takes the following arguments:

• roleId

# Sync calls
auth.deleteRole(roleId) # -> None`
auth.deleteRole(roleId='value') # -> None
# Async call
await asyncAuth.deleteRole(roleId) # -> None
await asyncAuth.deleteRole(roleId='value') # -> None

Expand Scopes

Return an expanded copy of the given scopeset, with scopes implied by any roles included.

This call uses the GET method with an HTTP body. It remains only for backward compatibility.

Required input schema

Required output schema

# Sync calls
auth.expandScopesGet(payload) # -> result`
# Async call
await asyncAuth.expandScopesGet(payload) # -> result

Expand Scopes

Return an expanded copy of the given scopeset, with scopes implied by any roles included.

Required input schema

Required output schema

# Sync calls
auth.expandScopes(payload) # -> result`
# Async call
await asyncAuth.expandScopes(payload) # -> result

Get Current Scopes

Return the expanded scopes available in the request, taking into account all sources of scopes and scope restrictions (temporary credentials, assumeScopes, client scopes, and roles).

Required output schema

# Sync calls
auth.currentScopes() # -> result`
# Async call
await asyncAuth.currentScopes() # -> result

Get Temporary Read/Write Credentials S3

Get temporary AWS credentials for read-write or read-only access to a given bucket and prefix within that bucket. The level parameter can be read-write or read-only and determines which type of credentials are returned. Please note that the level parameter is required in the scope guarding access. The bucket name must not contain ., as recommended by Amazon.

This method can only allow access to a whitelisted set of buckets. To add a bucket to that whitelist, contact the Taskcluster team, who will add it to the appropriate IAM policy. If the bucket is in a different AWS account, you will also need to add a bucket policy allowing access from the Taskcluster account. That policy should look like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "allow-taskcluster-auth-to-delegate-access",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::692406183521:root"
      },
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket>",
        "arn:aws:s3:::<bucket>/*"
      ]
    }
  ]
}

The credentials are set to expire after an hour, but this behavior is subject to change. Hence, you should always read the expires property from the response, if you intend to maintain active credentials in your application.

Please note that your prefix may not start with slash /. Such a prefix is allowed on S3, but we forbid it here to discourage bad behavior.

Also note that if your prefix doesn't end in a slash /, the STS credentials may allow access to unexpected keys, as S3 does not treat slashes specially. For example, a prefix of my-folder will allow access to my-folder/file.txt as expected, but also to my-folder.txt, which may not be intended.

Finally, note that the PutObjectAcl call is not allowed. Passing a canned ACL other than private to PutObject is treated as a PutObjectAcl call, and will result in an access-denied error from AWS. This limitation is due to a security flaw in Amazon S3 which might otherwise allow indefinite access to uploaded objects.

EC2 metadata compatibility, if the querystring parameter ?format=iam-role-compat is given, the response will be compatible with the JSON exposed by the EC2 metadata service. This aims to ease compatibility for libraries and tools built to auto-refresh credentials. For details on the format returned by EC2 metadata service see: EC2 User Guide.

Takes the following arguments:

• level
• bucket
• prefix

Required output schema

# Sync calls
auth.awsS3Credentials(level, bucket, prefix) # -> result`
auth.awsS3Credentials(level='value', bucket='value', prefix='value') # -> result
# Async call
await asyncAuth.awsS3Credentials(level, bucket, prefix) # -> result
await asyncAuth.awsS3Credentials(level='value', bucket='value', prefix='value') # -> result

List Accounts Managed by Auth

Retrieve a list of all Azure accounts managed by Taskcluster Auth.

Required output schema

# Sync calls
auth.azureAccounts() # -> result`
# Async call
await asyncAuth.azureAccounts() # -> result

List Tables in an Account Managed by Auth

Retrieve a list of all tables in an account.

Takes the following arguments:

• account

Required output schema

# Sync calls
auth.azureTables(account) # -> result`
auth.azureTables(account='value') # -> result
# Async call
await asyncAuth.azureTables(account) # -> result
await asyncAuth.azureTables(account='value') # -> result

Get Shared-Access-Signature for Azure Table

Get a shared access signature (SAS) string for use with a specific Azure Table Storage table.

The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the table if it doesn't already exist.

Takes the following arguments:

• account
• table
• level

Required output schema

# Sync calls
auth.azureTableSAS(account, table, level) # -> result`
auth.azureTableSAS(account='value', table='value', level='value') # -> result
# Async call
await asyncAuth.azureTableSAS(account, table, level) # -> result
await asyncAuth.azureTableSAS(account='value', table='value', level='value') # -> result

List containers in an Account Managed by Auth

Retrieve a list of all containers in an account.

Takes the following arguments:

• account

Required output schema

# Sync calls
auth.azureContainers(account) # -> result`
auth.azureContainers(account='value') # -> result
# Async call
await asyncAuth.azureContainers(account) # -> result
await asyncAuth.azureContainers(account='value') # -> result

Get Shared-Access-Signature for Azure Container

Get a shared access signature (SAS) string for use with a specific Azure Blob Storage container.

The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the container if it doesn't already exist.

Takes the following arguments:

• account
• container
• level

Required output schema

# Sync calls
auth.azureContainerSAS(account, container, level) # -> result`
auth.azureContainerSAS(account='value', container='value', level='value') # -> result
# Async call
await asyncAuth.azureContainerSAS(account, container, level) # -> result
await asyncAuth.azureContainerSAS(account='value', container='value', level='value') # -> result

Get DSN for Sentry Project

Get temporary DSN (access credentials) for a sentry project. The credentials returned can be used with any Sentry client for up to 24 hours, after which the credentials will be automatically disabled.

If the project doesn't exist it will be created, and assigned to the initial team configured for this component. Contact a Sentry admin to have the project transferred to a team you have access to if needed

Takes the following arguments:

• project

Required output schema

# Sync calls
auth.sentryDSN(project) # -> result`
auth.sentryDSN(project='value') # -> result
# Async call
await asyncAuth.sentryDSN(project) # -> result
await asyncAuth.sentryDSN(project='value') # -> result

Get Token for Statsum Project

Get temporary token and baseUrl for sending metrics to statsum.

The token is valid for 24 hours, clients should refresh after expiration.

Takes the following arguments:

• project

Required output schema

# Sync calls
auth.statsumToken(project) # -> result`
auth.statsumToken(project='value') # -> result
# Async call
await asyncAuth.statsumToken(project) # -> result
await asyncAuth.statsumToken(project='value') # -> result

Get Token for Webhooktunnel Proxy

Get temporary token and id for connecting to webhooktunnel The token is valid for 96 hours, clients should refresh after expiration.

Required output schema

# Sync calls
auth.webhooktunnelToken() # -> result`
# Async call
await asyncAuth.webhooktunnelToken() # -> result

Authenticate Hawk Request

Validate the request signature given on input and return list of scopes that the authenticating client has.

This method is used by other services that wish rely on Taskcluster credentials for authentication. This way we can use Hawk without having the secret credentials leave this service.

Required input schema

Required output schema

# Sync calls
auth.authenticateHawk(payload) # -> result`
# Async call
await asyncAuth.authenticateHawk(payload) # -> result

Test Authentication

Utility method to test client implementations of Taskcluster authentication.

Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client's scopes are based on clientScopes in the request body.

The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked against requiredScopes from the request body. On success, the response contains the clientId and scopes as seen by the API method.

Required input schema

Required output schema

# Sync calls
auth.testAuthenticate(payload) # -> result`
# Async call
await asyncAuth.testAuthenticate(payload) # -> result

Test Authentication (GET)

Utility method similar to testAuthenticate, but with the GET method, so it can be used with signed URLs (bewits).

Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client's scopes are ['test:*', 'auth:create-client:test:*']. The call fails if the test:authenticate-get scope is not available.

The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked, just like any API call. On success, the response contains the clientId and scopes as seen by the API method.

This method may later be extended to allow specification of client and required scopes via query arguments.

Required output schema

# Sync calls
auth.testAuthenticateGet() # -> result`
# Async call
await asyncAuth.testAuthenticateGet() # -> result

Exchanges in taskcluster.AuthEvents

// Create AuthEvents client instance
import taskcluster
authEvents = taskcluster.AuthEvents(options)

The auth service, typically available at auth.taskcluster.net is responsible for storing credentials, managing assignment of scopes, and validation of request signatures from other services.

These exchanges provides notifications when credentials or roles are updated. This is mostly so that multiple instances of the auth service can purge their caches and synchronize state. But you are of course welcome to use these for other purposes, monitoring changes for example.

Client Created Messages

• authEvents.clientCreated(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Client Updated Messages

• authEvents.clientUpdated(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Client Deleted Messages

• authEvents.clientDeleted(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Role Created Messages

• authEvents.roleCreated(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Role Updated Messages

• authEvents.roleUpdated(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Role Deleted Messages

• authEvents.roleDeleted(routingKeyPattern) -> routingKey
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Methods in taskcluster.AwsProvisioner

import asyncio # Only for async 
// Create AwsProvisioner client instance
import taskcluster
import taskcluster.aio

awsProvisioner = taskcluster.AwsProvisioner(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncAwsProvisioner = taskcluster.aio.AwsProvisioner(options, session=session)

The AWS Provisioner is responsible for provisioning instances on EC2 for use in Taskcluster. The provisioner maintains a set of worker configurations which can be managed with an API that is typically available at aws-provisioner.taskcluster.net/v1. This API can also perform basic instance management tasks in addition to maintaining the internal state of worker type configuration information.

The Provisioner runs at a configurable interval. Each iteration of the provisioner fetches a current copy the state that the AWS EC2 api reports. In each iteration, we ask the Queue how many tasks are pending for that worker type. Based on the number of tasks pending and the scaling ratio, we may submit requests for new instances. We use pricing information, capacity and utility factor information to decide which instance type in which region would be the optimal configuration.

Each EC2 instance type will declare a capacity and utility factor. Capacity is the number of tasks that a given machine is capable of running concurrently. Utility factor is a relative measure of performance between two instance types. We multiply the utility factor by the spot price to compare instance types and regions when making the bidding choices.

When a new EC2 instance is instantiated, its user data contains a token in securityToken that can be used with the getSecret method to retrieve the worker's credentials and any needed passwords or other restricted information. The worker is responsible for deleting the secret after retrieving it, to prevent dissemination of the secret to other proceses which can read the instance user data.

List worker types with details

Return a list of worker types, including some summary information about current capacity for each. While this list includes all defined worker types, there may be running EC2 instances for deleted worker types that are not included here. The list is unordered.

Required output schema

# Sync calls
awsProvisioner.listWorkerTypeSummaries() # -> result`
# Async call
await asyncAwsProvisioner.listWorkerTypeSummaries() # -> result

Create new Worker Type

Create a worker type. A worker type contains all the configuration needed for the provisioner to manage the instances. Each worker type knows which regions and which instance types are allowed for that worker type. Remember that Capacity is the number of concurrent tasks that can be run on a given EC2 resource and that Utility is the relative performance rate between different instance types. There is no way to configure different regions to have different sets of instance types so ensure that all instance types are available in all regions. This function is idempotent.

Once a worker type is in the provisioner, a back ground process will begin creating instances for it based on its capacity bounds and its pending task count from the Queue. It is the worker's responsibility to shut itself down. The provisioner has a limit (currently 96hours) for all instances to prevent zombie instances from running indefinitely.

The provisioner will ensure that all instances created are tagged with aws resource tags containing the provisioner id and the worker type.

If provided, the secrets in the global, region and instance type sections are available using the secrets api. If specified, the scopes provided will be used to generate a set of temporary credentials available with the other secrets.

Takes the following arguments:

• workerType

Required input schema

Required output schema

# Sync calls
awsProvisioner.createWorkerType(workerType, payload) # -> result`
awsProvisioner.createWorkerType(payload, workerType='value') # -> result
# Async call
await asyncAwsProvisioner.createWorkerType(workerType, payload) # -> result
await asyncAwsProvisioner.createWorkerType(payload, workerType='value') # -> result

Update Worker Type

Provide a new copy of a worker type to replace the existing one. This will overwrite the existing worker type definition if there is already a worker type of that name. This method will return a 200 response along with a copy of the worker type definition created Note that if you are using the result of a GET on the worker-type end point that you will need to delete the lastModified and workerType keys from the object returned, since those fields are not allowed the request body for this method

Otherwise, all input requirements and actions are the same as the create method.

Takes the following arguments:

• workerType

Required input schema

Required output schema

# Sync calls
awsProvisioner.updateWorkerType(workerType, payload) # -> result`
awsProvisioner.updateWorkerType(payload, workerType='value') # -> result
# Async call
await asyncAwsProvisioner.updateWorkerType(workerType, payload) # -> result
await asyncAwsProvisioner.updateWorkerType(payload, workerType='value') # -> result

Get Worker Type Last Modified Time

This method is provided to allow workers to see when they were last modified. The value provided through UserData can be compared against this value to see if changes have been made If the worker type definition has not been changed, the date should be identical as it is the same stored value.

Takes the following arguments:

• workerType

Required output schema

# Sync calls
awsProvisioner.workerTypeLastModified(workerType) # -> result`
awsProvisioner.workerTypeLastModified(workerType='value') # -> result
# Async call
await asyncAwsProvisioner.workerTypeLastModified(workerType) # -> result
await asyncAwsProvisioner.workerTypeLastModified(workerType='value') # -> result

Get Worker Type

Retrieve a copy of the requested worker type definition. This copy contains a lastModified field as well as the worker type name. As such, it will require manipulation to be able to use the results of this method to submit date to the update method.

Takes the following arguments:

• workerType

Required output schema

# Sync calls
awsProvisioner.workerType(workerType) # -> result`
awsProvisioner.workerType(workerType='value') # -> result
# Async call
await asyncAwsProvisioner.workerType(workerType) # -> result
await asyncAwsProvisioner.workerType(workerType='value') # -> result

Delete Worker Type

Delete a worker type definition. This method will only delete the worker type definition from the storage table. The actual deletion will be handled by a background worker. As soon as this method is called for a worker type, the background worker will immediately submit requests to cancel all spot requests for this worker type as well as killing all instances regardless of their state. If you want to gracefully remove a worker type, you must either ensure that no tasks are created with that worker type name or you could theoretically set maxCapacity to 0, though, this is not a supported or tested action

Takes the following arguments:

• workerType

# Sync calls
awsProvisioner.removeWorkerType(workerType) # -> None`
awsProvisioner.removeWorkerType(workerType='value') # -> None
# Async call
await asyncAwsProvisioner.removeWorkerType(workerType) # -> None
await asyncAwsProvisioner.removeWorkerType(workerType='value') # -> None

List Worker Types

Return a list of string worker type names. These are the names of all managed worker types known to the provisioner. This does not include worker types which are left overs from a deleted worker type definition but are still running in AWS.

Required output schema

# Sync calls
awsProvisioner.listWorkerTypes() # -> result`
# Async call
await asyncAwsProvisioner.listWorkerTypes() # -> result

Create new Secret

Insert a secret into the secret storage. The supplied secrets will be provided verbatime via getSecret, while the supplied scopes will be converted into credentials by getSecret.

This method is not ordinarily used in production; instead, the provisioner creates a new secret directly for each spot bid.

Takes the following arguments:

• token

Required input schema

# Sync calls
awsProvisioner.createSecret(token, payload) # -> None`
awsProvisioner.createSecret(payload, token='value') # -> None
# Async call
await asyncAwsProvisioner.createSecret(token, payload) # -> None
await asyncAwsProvisioner.createSecret(payload, token='value') # -> None

Get a Secret

Retrieve a secret from storage. The result contains any passwords or other restricted information verbatim as well as a temporary credential based on the scopes specified when the secret was created.

It is important that this secret is deleted by the consumer (removeSecret), or else the secrets will be visible to any process which can access the user data associated with the instance.

Takes the following arguments:

• token

Required output schema

# Sync calls
awsProvisioner.getSecret(token) # -> result`
awsProvisioner.getSecret(token='value') # -> result
# Async call
await asyncAwsProvisioner.getSecret(token) # -> result
await asyncAwsProvisioner.getSecret(token='value') # -> result

Report an instance starting

An instance will report in by giving its instance id as well as its security token. The token is given and checked to ensure that it matches a real token that exists to ensure that random machines do not check in. We could generate a different token but that seems like overkill

Takes the following arguments:

• instanceId
• token

# Sync calls
awsProvisioner.instanceStarted(instanceId, token) # -> None`
awsProvisioner.instanceStarted(instanceId='value', token='value') # -> None
# Async call
await asyncAwsProvisioner.instanceStarted(instanceId, token) # -> None
await asyncAwsProvisioner.instanceStarted(instanceId='value', token='value') # -> None

Remove a Secret

Remove a secret. After this call, a call to getSecret with the given token will return no information.

It is very important that the consumer of a secret delete the secret from storage before handing over control to untrusted processes to prevent credential and/or secret leakage.

Takes the following arguments:

• token

# Sync calls
awsProvisioner.removeSecret(token) # -> None`
awsProvisioner.removeSecret(token='value') # -> None
# Async call
await asyncAwsProvisioner.removeSecret(token) # -> None
await asyncAwsProvisioner.removeSecret(token='value') # -> None

Get All Launch Specifications for WorkerType

This method returns a preview of all possible launch specifications that this worker type definition could submit to EC2. It is used to test worker types, nothing more

This API end-point is experimental and may be subject to change without warning.

Takes the following arguments:

• workerType

Required output schema

# Sync calls
awsProvisioner.getLaunchSpecs(workerType) # -> result`
awsProvisioner.getLaunchSpecs(workerType='value') # -> result
# Async call
await asyncAwsProvisioner.getLaunchSpecs(workerType) # -> result
await asyncAwsProvisioner.getLaunchSpecs(workerType='value') # -> result

Get AWS State for a worker type

Return the state of a given workertype as stored by the provisioner. This state is stored as three lists: 1 for running instances, 1 for pending requests. The summary property contains an updated summary similar to that returned from listWorkerTypeSummaries.

Takes the following arguments:

• workerType

# Sync calls
awsProvisioner.state(workerType) # -> None`
awsProvisioner.state(workerType='value') # -> None
# Async call
await asyncAwsProvisioner.state(workerType) # -> None
await asyncAwsProvisioner.state(workerType='value') # -> None

Backend Status

This endpoint is used to show when the last time the provisioner has checked in. A check in is done through the deadman's snitch api. It is done at the conclusion of a provisioning iteration and used to tell if the background provisioning process is still running.

Warning this api end-point is not stable.

Required output schema

# Sync calls
awsProvisioner.backendStatus() # -> result`
# Async call
await asyncAwsProvisioner.backendStatus() # -> result

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
awsProvisioner.ping() # -> None`
# Async call
await asyncAwsProvisioner.ping() # -> None

Exchanges in taskcluster.AwsProvisionerEvents

// Create AwsProvisionerEvents client instance
import taskcluster
awsProvisionerEvents = taskcluster.AwsProvisionerEvents(options)

Exchanges from the provisioner... more docs later

WorkerType Created Message

• awsProvisionerEvents.workerTypeCreated(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • workerType is required Description: WorkerType that this message concerns.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

WorkerType Updated Message

• awsProvisionerEvents.workerTypeUpdated(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • workerType is required Description: WorkerType that this message concerns.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

WorkerType Removed Message

• awsProvisionerEvents.workerTypeRemoved(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • workerType is required Description: WorkerType that this message concerns.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Methods in taskcluster.EC2Manager

import asyncio # Only for async 
// Create EC2Manager client instance
import taskcluster
import taskcluster.aio

eC2Manager = taskcluster.EC2Manager(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncEC2Manager = taskcluster.aio.EC2Manager(options, session=session)

A taskcluster service which manages EC2 instances. This service does not understand any taskcluster concepts intrinsicaly other than using the name workerType to refer to a group of associated instances. Unless you are working on building a provisioner for AWS, you almost certainly do not want to use this service

See the list of worker types which are known to be managed

This method is only for debugging the ec2-manager

Required output schema

# Sync calls
eC2Manager.listWorkerTypes() # -> result`
# Async call
await asyncEC2Manager.listWorkerTypes() # -> result

Run an instance

Request an instance of a worker type

Takes the following arguments:

• workerType

Required input schema

# Sync calls
eC2Manager.runInstance(workerType, payload) # -> None`
eC2Manager.runInstance(payload, workerType='value') # -> None
# Async call
await asyncEC2Manager.runInstance(workerType, payload) # -> None
await asyncEC2Manager.runInstance(payload, workerType='value') # -> None

Terminate all resources from a worker type

Terminate all instances for this worker type

Takes the following arguments:

• workerType

# Sync calls
eC2Manager.terminateWorkerType(workerType) # -> None`
eC2Manager.terminateWorkerType(workerType='value') # -> None
# Async call
await asyncEC2Manager.terminateWorkerType(workerType) # -> None
await asyncEC2Manager.terminateWorkerType(workerType='value') # -> None

Look up the resource stats for a workerType

Return an object which has a generic state description. This only contains counts of instances

Takes the following arguments:

• workerType

Required output schema

# Sync calls
eC2Manager.workerTypeStats(workerType) # -> result`
eC2Manager.workerTypeStats(workerType='value') # -> result
# Async call
await asyncEC2Manager.workerTypeStats(workerType) # -> result
await asyncEC2Manager.workerTypeStats(workerType='value') # -> result

Look up the resource health for a workerType

Return a view of the health of a given worker type

Takes the following arguments:

• workerType

Required output schema

# Sync calls
eC2Manager.workerTypeHealth(workerType) # -> result`
eC2Manager.workerTypeHealth(workerType='value') # -> result
# Async call
await asyncEC2Manager.workerTypeHealth(workerType) # -> result
await asyncEC2Manager.workerTypeHealth(workerType='value') # -> result

Look up the most recent errors of a workerType

Return a list of the most recent errors encountered by a worker type

Takes the following arguments:

• workerType

Required output schema

# Sync calls
eC2Manager.workerTypeErrors(workerType) # -> result`
eC2Manager.workerTypeErrors(workerType='value') # -> result
# Async call
await asyncEC2Manager.workerTypeErrors(workerType) # -> result
await asyncEC2Manager.workerTypeErrors(workerType='value') # -> result

Look up the resource state for a workerType

Return state information for a given worker type

Takes the following arguments:

• workerType

Required output schema

# Sync calls
eC2Manager.workerTypeState(workerType) # -> result`
eC2Manager.workerTypeState(workerType='value') # -> result
# Async call
await asyncEC2Manager.workerTypeState(workerType) # -> result
await asyncEC2Manager.workerTypeState(workerType='value') # -> result

Ensure a KeyPair for a given worker type exists

Idempotently ensure that a keypair of a given name exists

Takes the following arguments:

• name

Required input schema

# Sync calls
eC2Manager.ensureKeyPair(name, payload) # -> None`
eC2Manager.ensureKeyPair(payload, name='value') # -> None
# Async call
await asyncEC2Manager.ensureKeyPair(name, payload) # -> None
await asyncEC2Manager.ensureKeyPair(payload, name='value') # -> None

Ensure a KeyPair for a given worker type does not exist

Ensure that a keypair of a given name does not exist.

Takes the following arguments:

• name

# Sync calls
eC2Manager.removeKeyPair(name) # -> None`
eC2Manager.removeKeyPair(name='value') # -> None
# Async call
await asyncEC2Manager.removeKeyPair(name) # -> None
await asyncEC2Manager.removeKeyPair(name='value') # -> None

Terminate an instance

Terminate an instance in a specified region

Takes the following arguments:

• region
• instanceId

# Sync calls
eC2Manager.terminateInstance(region, instanceId) # -> None`
eC2Manager.terminateInstance(region='value', instanceId='value') # -> None
# Async call
await asyncEC2Manager.terminateInstance(region, instanceId) # -> None
await asyncEC2Manager.terminateInstance(region='value', instanceId='value') # -> None

Request prices for EC2

Return a list of possible prices for EC2

Required output schema

# Sync calls
eC2Manager.getPrices() # -> result`
# Async call
await asyncEC2Manager.getPrices() # -> result

Request prices for EC2

Return a list of possible prices for EC2

Required input schema

Required output schema

# Sync calls
eC2Manager.getSpecificPrices(payload) # -> result`
# Async call
await asyncEC2Manager.getSpecificPrices(payload) # -> result

Get EC2 account health metrics

Give some basic stats on the health of our EC2 account

Required output schema

# Sync calls
eC2Manager.getHealth() # -> result`
# Async call
await asyncEC2Manager.getHealth() # -> result

Look up the most recent errors in the provisioner across all worker types

Return a list of recent errors encountered

Required output schema

# Sync calls
eC2Manager.getRecentErrors() # -> result`
# Async call
await asyncEC2Manager.getRecentErrors() # -> result

See the list of regions managed by this ec2-manager

This method is only for debugging the ec2-manager

# Sync calls
eC2Manager.regions() # -> None`
# Async call
await asyncEC2Manager.regions() # -> None

See the list of AMIs and their usage

List AMIs and their usage by returning a list of objects in the form: { region: string volumetype: string lastused: timestamp }

# Sync calls
eC2Manager.amiUsage() # -> None`
# Async call
await asyncEC2Manager.amiUsage() # -> None

See the current EBS volume usage list

Lists current EBS volume usage by returning a list of objects that are uniquely defined by {region, volumetype, state} in the form: { region: string, volumetype: string, state: string, totalcount: integer, totalgb: integer, touched: timestamp (last time that information was updated), }

# Sync calls
eC2Manager.ebsUsage() # -> None`
# Async call
await asyncEC2Manager.ebsUsage() # -> None

Statistics on the Database client pool

This method is only for debugging the ec2-manager

# Sync calls
eC2Manager.dbpoolStats() # -> None`
# Async call
await asyncEC2Manager.dbpoolStats() # -> None

List out the entire internal state

This method is only for debugging the ec2-manager

# Sync calls
eC2Manager.allState() # -> None`
# Async call
await asyncEC2Manager.allState() # -> None

Statistics on the sqs queues

This method is only for debugging the ec2-manager

# Sync calls
eC2Manager.sqsStats() # -> None`
# Async call
await asyncEC2Manager.sqsStats() # -> None

Purge the SQS queues

This method is only for debugging the ec2-manager

# Sync calls
eC2Manager.purgeQueues() # -> None`
# Async call
await asyncEC2Manager.purgeQueues() # -> None

API Reference

Generate an API reference for this service

# Sync calls
eC2Manager.apiReference() # -> None`
# Async call
await asyncEC2Manager.apiReference() # -> None

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
eC2Manager.ping() # -> None`
# Async call
await asyncEC2Manager.ping() # -> None

Methods in taskcluster.Github

import asyncio # Only for async 
// Create Github client instance
import taskcluster
import taskcluster.aio

github = taskcluster.Github(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncGithub = taskcluster.aio.Github(options, session=session)

The github service, typically available at github.taskcluster.net, is responsible for publishing pulse messages in response to GitHub events.

This document describes the API end-point for consuming GitHub web hooks, as well as some useful consumer APIs.

When Github forbids an action, this service returns an HTTP 403 with code ForbiddenByGithub.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
github.ping() # -> None`
# Async call
await asyncGithub.ping() # -> None

Consume GitHub WebHook

Capture a GitHub event and publish it via pulse, if it's a push, release or pull request.

# Sync calls
github.githubWebHookConsumer() # -> None`
# Async call
await asyncGithub.githubWebHookConsumer() # -> None

List of Builds

A paginated list of builds that have been run in Taskcluster. Can be filtered on various git-specific fields.

Required output schema

# Sync calls
github.builds() # -> result`
# Async call
await asyncGithub.builds() # -> result

Latest Build Status Badge

Checks the status of the latest build of a given branch and returns corresponding badge svg.

Takes the following arguments:

• owner
• repo
• branch

# Sync calls
github.badge(owner, repo, branch) # -> None`
github.badge(owner='value', repo='value', branch='value') # -> None
# Async call
await asyncGithub.badge(owner, repo, branch) # -> None
await asyncGithub.badge(owner='value', repo='value', branch='value') # -> None

Get Repository Info

Returns any repository metadata that is useful within Taskcluster related services.

Takes the following arguments:

• owner
• repo

Required output schema

# Sync calls
github.repository(owner, repo) # -> result`
github.repository(owner='value', repo='value') # -> result
# Async call
await asyncGithub.repository(owner, repo) # -> result
await asyncGithub.repository(owner='value', repo='value') # -> result

Latest Status for Branch

For a given branch of a repository, this will always point to a status page for the most recent task triggered by that branch.

Note: This is a redirect rather than a direct link.

Takes the following arguments:

• owner
• repo
• branch

# Sync calls
github.latest(owner, repo, branch) # -> None`
github.latest(owner='value', repo='value', branch='value') # -> None
# Async call
await asyncGithub.latest(owner, repo, branch) # -> None
await asyncGithub.latest(owner='value', repo='value', branch='value') # -> None

Post a status against a given changeset

For a given changeset (SHA) of a repository, this will attach a "commit status" on github. These statuses are links displayed next to each revision. The status is either OK (green check) or FAILURE (red cross), made of a custom title and link.

Takes the following arguments:

• owner
• repo
• sha

Required input schema

# Sync calls
github.createStatus(owner, repo, sha, payload) # -> None`
github.createStatus(payload, owner='value', repo='value', sha='value') # -> None
# Async call
await asyncGithub.createStatus(owner, repo, sha, payload) # -> None
await asyncGithub.createStatus(payload, owner='value', repo='value', sha='value') # -> None

Post a comment on a given GitHub Issue or Pull Request

For a given Issue or Pull Request of a repository, this will write a new message.

Takes the following arguments:

• owner
• repo
• number

Required input schema

# Sync calls
github.createComment(owner, repo, number, payload) # -> None`
github.createComment(payload, owner='value', repo='value', number='value') # -> None
# Async call
await asyncGithub.createComment(owner, repo, number, payload) # -> None
await asyncGithub.createComment(payload, owner='value', repo='value', number='value') # -> None

Exchanges in taskcluster.GithubEvents

// Create GithubEvents client instance
import taskcluster
githubEvents = taskcluster.GithubEvents(options)

The github service publishes a pulse message for supported github events, translating Github webhook events into pulse messages.

This document describes the exchange offered by the taskcluster github service

GitHub Pull Request Event

• githubEvents.pullRequest(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always "primary" for the formalized routing key.
  • organization is required Description: The GitHub organization which had an event. All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.
  • repository is required Description: The GitHub repository which had an event.All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.
  • action is required Description: The GitHub action which triggered an event. See for possible values see the payload actions property.

GitHub push Event

• githubEvents.push(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always "primary" for the formalized routing key.
  • organization is required Description: The GitHub organization which had an event. All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.
  • repository is required Description: The GitHub repository which had an event.All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.

GitHub release Event

• githubEvents.release(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always "primary" for the formalized routing key.
  • organization is required Description: The GitHub organization which had an event. All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.
  • repository is required Description: The GitHub repository which had an event.All periods have been replaced by % - such that foo.bar becomes foo%bar - and all other special characters aside from - and _ have been stripped.

Methods in taskcluster.Hooks

import asyncio # Only for async 
// Create Hooks client instance
import taskcluster
import taskcluster.aio

hooks = taskcluster.Hooks(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncHooks = taskcluster.aio.Hooks(options, session=session)

Hooks are a mechanism for creating tasks in response to events.

Hooks are identified with a hookGroupId and a hookId.

When an event occurs, the resulting task is automatically created. The task is created using the scope assume:hook-id:<hookGroupId>/<hookId>, which must have scopes to make the createTask call, including satisfying all scopes in task.scopes. The new task has a taskGroupId equal to its taskId, as is the convention for decision tasks.

Hooks can have a "schedule" indicating specific times that new tasks should be created. Each schedule is in a simple cron format, per https://www.npmjs.com/package/cron-parser. For example:

• ['0 0 1 * * *'] -- daily at 1:00 UTC
• ['0 0 9,21 * * 1-5', '0 0 12 * * 0,6'] -- weekdays at 9:00 and 21:00 UTC, weekends at noon

The task definition is used as a JSON-e template, with a context depending on how it is fired. See https://docs.taskcluster.net/reference/core/taskcluster-hooks/docs/firing-hooks for more information.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
hooks.ping() # -> None`
# Async call
await asyncHooks.ping() # -> None

List hook groups

This endpoint will return a list of all hook groups with at least one hook.

Required output schema

# Sync calls
hooks.listHookGroups() # -> result`
# Async call
await asyncHooks.listHookGroups() # -> result

List hooks in a given group

This endpoint will return a list of all the hook definitions within a given hook group.

Takes the following arguments:

• hookGroupId

Required output schema

# Sync calls
hooks.listHooks(hookGroupId) # -> result`
hooks.listHooks(hookGroupId='value') # -> result
# Async call
await asyncHooks.listHooks(hookGroupId) # -> result
await asyncHooks.listHooks(hookGroupId='value') # -> result

Get hook definition

This endpoint will return the hook definition for the given hookGroupId and hookId.

Takes the following arguments:

• hookGroupId
• hookId

Required output schema

# Sync calls
hooks.hook(hookGroupId, hookId) # -> result`
hooks.hook(hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.hook(hookGroupId, hookId) # -> result
await asyncHooks.hook(hookGroupId='value', hookId='value') # -> result

Get hook status

This endpoint will return the current status of the hook. This represents a snapshot in time and may vary from one call to the next.

Takes the following arguments:

• hookGroupId
• hookId

Required output schema

# Sync calls
hooks.getHookStatus(hookGroupId, hookId) # -> result`
hooks.getHookStatus(hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.getHookStatus(hookGroupId, hookId) # -> result
await asyncHooks.getHookStatus(hookGroupId='value', hookId='value') # -> result

Create a hook

This endpoint will create a new hook.

The caller's credentials must include the role that will be used to create the task. That role must satisfy task.scopes as well as the necessary scopes to add the task to the queue.

Takes the following arguments:

• hookGroupId
• hookId

Required input schema

Required output schema

# Sync calls
hooks.createHook(hookGroupId, hookId, payload) # -> result`
hooks.createHook(payload, hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.createHook(hookGroupId, hookId, payload) # -> result
await asyncHooks.createHook(payload, hookGroupId='value', hookId='value') # -> result

Update a hook

This endpoint will update an existing hook. All fields except hookGroupId and hookId can be modified.

Takes the following arguments:

• hookGroupId
• hookId

Required input schema

Required output schema

# Sync calls
hooks.updateHook(hookGroupId, hookId, payload) # -> result`
hooks.updateHook(payload, hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.updateHook(hookGroupId, hookId, payload) # -> result
await asyncHooks.updateHook(payload, hookGroupId='value', hookId='value') # -> result

Delete a hook

This endpoint will remove a hook definition.

Takes the following arguments:

• hookGroupId
• hookId

# Sync calls
hooks.removeHook(hookGroupId, hookId) # -> None`
hooks.removeHook(hookGroupId='value', hookId='value') # -> None
# Async call
await asyncHooks.removeHook(hookGroupId, hookId) # -> None
await asyncHooks.removeHook(hookGroupId='value', hookId='value') # -> None

Trigger a hook

This endpoint will trigger the creation of a task from a hook definition.

The HTTP payload must match the hooks triggerSchema. If it does, it is provided as the payload property of the JSON-e context used to render the task template.

Takes the following arguments:

• hookGroupId
• hookId

Required input schema

Required output schema

# Sync calls
hooks.triggerHook(hookGroupId, hookId, payload) # -> result`
hooks.triggerHook(payload, hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.triggerHook(hookGroupId, hookId, payload) # -> result
await asyncHooks.triggerHook(payload, hookGroupId='value', hookId='value') # -> result

Get a trigger token

Retrieve a unique secret token for triggering the specified hook. This token can be deactivated with resetTriggerToken.

Takes the following arguments:

• hookGroupId
• hookId

Required output schema

# Sync calls
hooks.getTriggerToken(hookGroupId, hookId) # -> result`
hooks.getTriggerToken(hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.getTriggerToken(hookGroupId, hookId) # -> result
await asyncHooks.getTriggerToken(hookGroupId='value', hookId='value') # -> result

Reset a trigger token

Reset the token for triggering a given hook. This invalidates token that may have been issued via getTriggerToken with a new token.

Takes the following arguments:

• hookGroupId
• hookId

Required output schema

# Sync calls
hooks.resetTriggerToken(hookGroupId, hookId) # -> result`
hooks.resetTriggerToken(hookGroupId='value', hookId='value') # -> result
# Async call
await asyncHooks.resetTriggerToken(hookGroupId, hookId) # -> result
await asyncHooks.resetTriggerToken(hookGroupId='value', hookId='value') # -> result

Trigger a hook with a token

This endpoint triggers a defined hook with a valid token.

The HTTP payload must match the hooks triggerSchema. If it does, it is provided as the payload property of the JSON-e context used to render the task template.

Takes the following arguments:

• hookGroupId
• hookId
• token

Required input schema

Required output schema

# Sync calls
hooks.triggerHookWithToken(hookGroupId, hookId, token, payload) # -> result`
hooks.triggerHookWithToken(payload, hookGroupId='value', hookId='value', token='value') # -> result
# Async call
await asyncHooks.triggerHookWithToken(hookGroupId, hookId, token, payload) # -> result
await asyncHooks.triggerHookWithToken(payload, hookGroupId='value', hookId='value', token='value') # -> result

Methods in taskcluster.Index

import asyncio # Only for async 
// Create Index client instance
import taskcluster
import taskcluster.aio

index = taskcluster.Index(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncIndex = taskcluster.aio.Index(options, session=session)

The task index, typically available at index.taskcluster.net, is responsible for indexing tasks. The service ensures that tasks can be located by recency and/or arbitrary strings. Common use-cases include:

• Locate tasks by git or mercurial <revision>, or
• Locate latest task from given <branch>, such as a release.

Index hierarchy, tasks are indexed in a dot (.) separated hierarchy called a namespace. For example a task could be indexed with the index path some-app.<revision>.linux-64.release-build. In this case the following namespaces is created.

1. some-app,
2. some-app.<revision>, and,
3. some-app.<revision>.linux-64

Inside the namespace some-app.<revision> you can find the namespace some-app.<revision>.linux-64 inside which you can find the indexed task some-app.<revision>.linux-64.release-build. This is an example of indexing builds for a given platform and revision.

Task Rank, when a task is indexed, it is assigned a rank (defaults to 0). If another task is already indexed in the same namespace with lower or equal rank, the index for that task will be overwritten. For example consider index path mozilla-central.linux-64.release-build. In this case one might choose to use a UNIX timestamp or mercurial revision number as rank. This way the latest completed linux 64 bit release build is always available at mozilla-central.linux-64.release-build.

Note that this does mean index paths are not immutable: the same path may point to a different task now than it did a moment ago.

Indexed Data, when a task is retrieved from the index the result includes a taskId and an additional user-defined JSON blob that was indexed with the task.

Entry Expiration, all indexed entries must have an expiration date. Typically this defaults to one year, if not specified. If you are indexing tasks to make it easy to find artifacts, consider using the artifact's expiration date.

Valid Characters, all keys in a namespace <key1>.<key2> must be in the form /[a-zA-Z0-9_!~*'()%-]+/. Observe that this is URL-safe and that if you strictly want to put another character you can URL encode it.

Indexing Routes, tasks can be indexed using the API below, but the most common way to index tasks is adding a custom route to task.routes of the form index.<namespace>. In order to add this route to a task you'll need the scope queue:route:index.<namespace>. When a task has this route, it will be indexed when the task is completed successfully. The task will be indexed with rank, data and expires as specified in task.extra.index. See the example below:

{
  payload:  { /* ... */ },
  routes: [
    // index.<namespace> prefixed routes, tasks CC'ed such a route will
    // be indexed under the given <namespace>
    "index.mozilla-central.linux-64.release-build",
    "index.<revision>.linux-64.release-build"
  ],
  extra: {
    // Optional details for indexing service
    index: {
      // Ordering, this taskId will overwrite any thing that has
      // rank <= 4000 (defaults to zero)
      rank:       4000,

      // Specify when the entries expire (Defaults to 1 year)
      expires:          new Date().toJSON(),

      // A little informal data to store along with taskId
      // (less 16 kb when encoded as JSON)
      data: {
        hgRevision:   "...",
        commitMessae: "...",
        whatever...
      }
    },
    // Extra properties for other services...
  }
  // Other task properties...
}

Remark, when indexing tasks using custom routes, it's also possible to listen for messages about these tasks. For example one could bind to route.index.some-app.*.release-build, and pick up all messages about release builds. Hence, it is a good idea to document task index hierarchies, as these make up extension points in their own.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
index.ping() # -> None`
# Async call
await asyncIndex.ping() # -> None

Find Indexed Task

Find a task by index path, returning the highest-rank task with that path. If no task exists for the given path, this API end-point will respond with a 404 status.

Takes the following arguments:

• indexPath

Required output schema

# Sync calls
index.findTask(indexPath) # -> result`
index.findTask(indexPath='value') # -> result
# Async call
await asyncIndex.findTask(indexPath) # -> result
await asyncIndex.findTask(indexPath='value') # -> result

List Namespaces

List the namespaces immediately under a given namespace.

This endpoint lists up to 1000 namespaces. If more namespaces are present, a continuationToken will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.

Takes the following arguments:

• namespace

Required output schema

# Sync calls
index.listNamespaces(namespace) # -> result`
index.listNamespaces(namespace='value') # -> result
# Async call
await asyncIndex.listNamespaces(namespace) # -> result
await asyncIndex.listNamespaces(namespace='value') # -> result

List Tasks

List the tasks immediately under a given namespace.

This endpoint lists up to 1000 tasks. If more tasks are present, a continuationToken will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.

Remark, this end-point is designed for humans browsing for tasks, not services, as that makes little sense.

Takes the following arguments:

• namespace

Required output schema

# Sync calls
index.listTasks(namespace) # -> result`
index.listTasks(namespace='value') # -> result
# Async call
await asyncIndex.listTasks(namespace) # -> result
await asyncIndex.listTasks(namespace='value') # -> result

Insert Task into Index

Insert a task into the index. If the new rank is less than the existing rank at the given index path, the task is not indexed but the response is still 200 OK.

Please see the introduction above for information about indexing successfully completed tasks automatically using custom routes.

Takes the following arguments:

• namespace

Required input schema

Required output schema

# Sync calls
index.insertTask(namespace, payload) # -> result`
index.insertTask(payload, namespace='value') # -> result
# Async call
await asyncIndex.insertTask(namespace, payload) # -> result
await asyncIndex.insertTask(payload, namespace='value') # -> result

Get Artifact From Indexed Task

Find a task by index path and redirect to the artifact on the most recent run with the given name.

Note that multiple calls to this endpoint may return artifacts from differen tasks if a new task is inserted into the index between calls. Avoid using this method as a stable link to multiple, connected files if the index path does not contain a unique identifier. For example, the following two links may return unrelated files:

• https://index.taskcluster.net/task/some-app.win64.latest.installer/artifacts/public/installer.exe`
• https://index.taskcluster.net/task/some-app.win64.latest.installer/artifacts/public/debug-symbols.zip`

This problem be remedied by including the revision in the index path or by bundling both installer and debug symbols into a single artifact.

If no task exists for the given index path, this API end-point responds with 404.

Takes the following arguments:

• indexPath
• name

# Sync calls
index.findArtifactFromTask(indexPath, name) # -> None`
index.findArtifactFromTask(indexPath='value', name='value') # -> None
# Async call
await asyncIndex.findArtifactFromTask(indexPath, name) # -> None
await asyncIndex.findArtifactFromTask(indexPath='value', name='value') # -> None

Methods in taskcluster.Login

import asyncio # Only for async 
// Create Login client instance
import taskcluster
import taskcluster.aio

login = taskcluster.Login(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncLogin = taskcluster.aio.Login(options, session=session)

The Login service serves as the interface between external authentication systems and Taskcluster credentials.

Get Taskcluster credentials given a suitable access_token

Given an OIDC access_token from a trusted OpenID provider, return a set of Taskcluster credentials for use on behalf of the identified user.

This method is typically not called with a Taskcluster client library and does not accept Hawk credentials. The access_token should be given in an Authorization header:

Authorization: Bearer abc.xyz

The access_token is first verified against the named :provider, then passed to the provider's API to retrieve a user profile. That profile is then used to generate Taskcluster credentials appropriate to the user. Note that the resulting credentials may or may not include a certificate property. Callers should be prepared for either alternative.

The given credentials will expire in a relatively short time. Callers should monitor this expiration and refresh the credentials if necessary, by calling this endpoint again, if they have expired.

Takes the following arguments:

• provider

Required output schema

# Sync calls
login.oidcCredentials(provider) # -> result`
login.oidcCredentials(provider='value') # -> result
# Async call
await asyncLogin.oidcCredentials(provider) # -> result
await asyncLogin.oidcCredentials(provider='value') # -> result

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
login.ping() # -> None`
# Async call
await asyncLogin.ping() # -> None

Methods in taskcluster.Notify

import asyncio # Only for async 
// Create Notify client instance
import taskcluster
import taskcluster.aio

notify = taskcluster.Notify(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncNotify = taskcluster.aio.Notify(options, session=session)

The notification service, typically available at notify.taskcluster.net listens for tasks with associated notifications and handles requests to send emails and post pulse messages.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
notify.ping() # -> None`
# Async call
await asyncNotify.ping() # -> None

Send an Email

Send an email to address. The content is markdown and will be rendered to HTML, but both the HTML and raw markdown text will be sent in the email. If a link is included, it will be rendered to a nice button in the HTML version of the email

Required input schema

# Sync calls
notify.email(payload) # -> None`
# Async call
await asyncNotify.email(payload) # -> None

Publish a Pulse Message

Publish a message on pulse with the given routingKey.

Required input schema

# Sync calls
notify.pulse(payload) # -> None`
# Async call
await asyncNotify.pulse(payload) # -> None

Post IRC Message

Post a message on IRC to a specific channel or user, or a specific user on a specific channel.

Success of this API method does not imply the message was successfully posted. This API method merely inserts the IRC message into a queue that will be processed by a background process. This allows us to re-send the message in face of connection issues.

However, if the user isn't online the message will be dropped without error. We maybe improve this behavior in the future. For now just keep in mind that IRC is a best-effort service.

Required input schema

# Sync calls
notify.irc(payload) # -> None`
# Async call
await asyncNotify.irc(payload) # -> None

Methods in taskcluster.PurgeCache

import asyncio # Only for async 
// Create PurgeCache client instance
import taskcluster
import taskcluster.aio

purgeCache = taskcluster.PurgeCache(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncPurgeCache = taskcluster.aio.PurgeCache(options, session=session)

The purge-cache service, typically available at purge-cache.taskcluster.net, is responsible for publishing a pulse message for workers, so they can purge cache upon request.

This document describes the API end-point for publishing the pulse message. This is mainly intended to be used by tools.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
purgeCache.ping() # -> None`
# Async call
await asyncPurgeCache.ping() # -> None

Purge Worker Cache

Publish a purge-cache message to purge caches named cacheName with provisionerId and workerType in the routing-key. Workers should be listening for this message and purge caches when they see it.

Takes the following arguments:

• provisionerId
• workerType

Required input schema

# Sync calls
purgeCache.purgeCache(provisionerId, workerType, payload) # -> None`
purgeCache.purgeCache(payload, provisionerId='value', workerType='value') # -> None
# Async call
await asyncPurgeCache.purgeCache(provisionerId, workerType, payload) # -> None
await asyncPurgeCache.purgeCache(payload, provisionerId='value', workerType='value') # -> None

All Open Purge Requests

This is useful mostly for administors to view the set of open purge requests. It should not be used by workers. They should use the purgeRequests endpoint that is specific to their workerType and provisionerId.

Required output schema

# Sync calls
purgeCache.allPurgeRequests() # -> result`
# Async call
await asyncPurgeCache.allPurgeRequests() # -> result

Open Purge Requests for a provisionerId/workerType pair

List of caches that need to be purged if they are from before a certain time. This is safe to be used in automation from workers.

Takes the following arguments:

• provisionerId
• workerType

Required output schema

# Sync calls
purgeCache.purgeRequests(provisionerId, workerType) # -> result`
purgeCache.purgeRequests(provisionerId='value', workerType='value') # -> result
# Async call
await asyncPurgeCache.purgeRequests(provisionerId, workerType) # -> result
await asyncPurgeCache.purgeRequests(provisionerId='value', workerType='value') # -> result

Exchanges in taskcluster.PurgeCacheEvents

// Create PurgeCacheEvents client instance
import taskcluster
purgeCacheEvents = taskcluster.PurgeCacheEvents(options)

The purge-cache service, typically available at purge-cache.taskcluster.net, is responsible for publishing a pulse message for workers, so they can purge cache upon request.

This document describes the exchange offered for workers by the cache-purge service.

Purge Cache Messages

• purgeCacheEvents.purgeCache(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • provisionerId is required Description: provisionerId under which to purge cache.
  • workerType is required Description: workerType for which to purge cache.

Methods in taskcluster.Queue

import asyncio # Only for async 
// Create Queue client instance
import taskcluster
import taskcluster.aio

queue = taskcluster.Queue(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncQueue = taskcluster.aio.Queue(options, session=session)

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.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
queue.ping() # -> None`
# Async call
await asyncQueue.ping() # -> None

Get Task Definition

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.task(taskId) # -> result`
queue.task(taskId='value') # -> result
# Async call
await asyncQueue.task(taskId) # -> result
await asyncQueue.task(taskId='value') # -> result

Get task status

Get task status structure from taskId

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.status(taskId) # -> result`
queue.status(taskId='value') # -> result
# Async call
await asyncQueue.status(taskId) # -> result
await asyncQueue.status(taskId='value') # -> result

List Task Group

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.

Takes the following arguments:

• taskGroupId

Required output schema

# Sync calls
queue.listTaskGroup(taskGroupId) # -> result`
queue.listTaskGroup(taskGroupId='value') # -> result
# Async call
await asyncQueue.listTaskGroup(taskGroupId) # -> result
await asyncQueue.listTaskGroup(taskGroupId='value') # -> result

List Dependent Tasks

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.listDependentTasks(taskId) # -> result`
queue.listDependentTasks(taskId='value') # -> result
# Async call
await asyncQueue.listDependentTasks(taskId) # -> result
await asyncQueue.listDependentTasks(taskId='value') # -> result

Create New Task

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.

Scopes: Note that the scopes required to complete this API call depend on the content of the scopes, routes, schedulerId, priority, provisionerId, and workerType properties of the task definition.

Legacy Scopes: The queue:create-task:.. scope without a priority and the queue:define-task:.. and queue:task-group-id:.. scopes are considered legacy and should not be used. Note that the new, non-legacy scopes require a queue:scheduler-id:.. scope as well as scopes for the proper priority.

Takes the following arguments:

• taskId

Required input schema

Required output schema

# Sync calls
queue.createTask(taskId, payload) # -> result`
queue.createTask(payload, taskId='value') # -> result
# Async call
await asyncQueue.createTask(taskId, payload) # -> result
await asyncQueue.createTask(payload, taskId='value') # -> result

Define Task

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

Takes the following arguments:

• taskId

Required input schema

Required output schema

# Sync calls
queue.defineTask(taskId, payload) # -> result`
queue.defineTask(payload, taskId='value') # -> result
# Async call
await asyncQueue.defineTask(taskId, payload) # -> result
await asyncQueue.defineTask(payload, taskId='value') # -> result

Schedule Defined Task

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.scheduleTask(taskId) # -> result`
queue.scheduleTask(taskId='value') # -> result
# Async call
await asyncQueue.scheduleTask(taskId) # -> result
await asyncQueue.scheduleTask(taskId='value') # -> result

Rerun a Resolved Task

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.rerunTask(taskId) # -> result`
queue.rerunTask(taskId='value') # -> result
# Async call
await asyncQueue.rerunTask(taskId) # -> result
await asyncQueue.rerunTask(taskId='value') # -> result

Cancel Task

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.cancelTask(taskId) # -> result`
queue.cancelTask(taskId='value') # -> result
# Async call
await asyncQueue.cancelTask(taskId) # -> result
await asyncQueue.cancelTask(taskId='value') # -> result

Claim Work

Claim pending task(s) for the given provisionerId/workerType queue.

If any work is available (even if fewer than the requested number of tasks, this will return immediately. Otherwise, it will block for tens of seconds waiting for work. If no work appears, it will return an emtpy list of tasks. Callers should sleep a short while (to avoid denial of service in an error condition) and call the endpoint again. This is a simple implementation of "long polling".

Takes the following arguments:

• provisionerId
• workerType

Required input schema

Required output schema

# Sync calls
queue.claimWork(provisionerId, workerType, payload) # -> result`
queue.claimWork(payload, provisionerId='value', workerType='value') # -> result
# Async call
await asyncQueue.claimWork(provisionerId, workerType, payload) # -> result
await asyncQueue.claimWork(payload, provisionerId='value', workerType='value') # -> result

Claim Task

claim a task - never documented

Takes the following arguments:

• taskId
• runId

Required input schema

Required output schema

# Sync calls
queue.claimTask(taskId, runId, payload) # -> result`
queue.claimTask(payload, taskId='value', runId='value') # -> result
# Async call
await asyncQueue.claimTask(taskId, runId, payload) # -> result
await asyncQueue.claimTask(payload, taskId='value', runId='value') # -> result

Reclaim task

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.

Takes the following arguments:

• taskId
• runId

Required output schema

# Sync calls
queue.reclaimTask(taskId, runId) # -> result`
queue.reclaimTask(taskId='value', runId='value') # -> result
# Async call
await asyncQueue.reclaimTask(taskId, runId) # -> result
await asyncQueue.reclaimTask(taskId='value', runId='value') # -> result

Report Run Completed

Report a task completed, resolving the run as completed.

Takes the following arguments:

• taskId
• runId

Required output schema

# Sync calls
queue.reportCompleted(taskId, runId) # -> result`
queue.reportCompleted(taskId='value', runId='value') # -> result
# Async call
await asyncQueue.reportCompleted(taskId, runId) # -> result
await asyncQueue.reportCompleted(taskId='value', runId='value') # -> result

Report Run Failed

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.

Takes the following arguments:

• taskId
• runId

Required output schema

# Sync calls
queue.reportFailed(taskId, runId) # -> result`
queue.reportFailed(taskId='value', runId='value') # -> result
# Async call
await asyncQueue.reportFailed(taskId, runId) # -> result
await asyncQueue.reportFailed(taskId='value', runId='value') # -> result

Report Task Exception

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.

Takes the following arguments:

• taskId
• runId

Required input schema

Required output schema

# Sync calls
queue.reportException(taskId, runId, payload) # -> result`
queue.reportException(payload, taskId='value', runId='value') # -> result
# Async call
await asyncQueue.reportException(taskId, runId, payload) # -> result
await asyncQueue.reportException(payload, taskId='value', runId='value') # -> result

Create Artifact

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 424 (Failed Dependency) 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.

Takes the following arguments:

• taskId
• runId
• name

Required input schema

Required output schema

# Sync calls
queue.createArtifact(taskId, runId, name, payload) # -> result`
queue.createArtifact(payload, taskId='value', runId='value', name='value') # -> result
# Async call
await asyncQueue.createArtifact(taskId, runId, name, payload) # -> result
await asyncQueue.createArtifact(payload, taskId='value', runId='value', name='value') # -> result

Complete Artifact

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'

Takes the following arguments:

• taskId
• runId
• name

Required input schema

# Sync calls
queue.completeArtifact(taskId, runId, name, payload) # -> None`
queue.completeArtifact(payload, taskId='value', runId='value', name='value') # -> None
# Async call
await asyncQueue.completeArtifact(taskId, runId, name, payload) # -> None
await asyncQueue.completeArtifact(payload, taskId='value', runId='value', name='value') # -> None

Get Artifact from Run

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!)

Takes the following arguments:

• taskId
• runId
• name

# Sync calls
queue.getArtifact(taskId, runId, name) # -> None`
queue.getArtifact(taskId='value', runId='value', name='value') # -> None
# Async call
await asyncQueue.getArtifact(taskId, runId, name) # -> None
await asyncQueue.getArtifact(taskId='value', runId='value', name='value') # -> None

Get Artifact from Latest Run

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.

Takes the following arguments:

• taskId
• name

# Sync calls
queue.getLatestArtifact(taskId, name) # -> None`
queue.getLatestArtifact(taskId='value', name='value') # -> None
# Async call
await asyncQueue.getLatestArtifact(taskId, name) # -> None
await asyncQueue.getLatestArtifact(taskId='value', name='value') # -> None

Get Artifacts from Run

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.

Takes the following arguments:

• taskId
• runId

Required output schema

# Sync calls
queue.listArtifacts(taskId, runId) # -> result`
queue.listArtifacts(taskId='value', runId='value') # -> result
# Async call
await asyncQueue.listArtifacts(taskId, runId) # -> result
await asyncQueue.listArtifacts(taskId='value', runId='value') # -> result

Get Artifacts from Latest Run

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.

Takes the following arguments:

• taskId

Required output schema

# Sync calls
queue.listLatestArtifacts(taskId) # -> result`
queue.listLatestArtifacts(taskId='value') # -> result
# Async call
await asyncQueue.listLatestArtifacts(taskId) # -> result
await asyncQueue.listLatestArtifacts(taskId='value') # -> result

Get a list of all active provisioners

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.

Required output schema

# Sync calls
queue.listProvisioners() # -> result`
# Async call
await asyncQueue.listProvisioners() # -> result

Get an active provisioner

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.

Takes the following arguments:

• provisionerId

Required output schema

# Sync calls
queue.getProvisioner(provisionerId) # -> result`
queue.getProvisioner(provisionerId='value') # -> result
# Async call
await asyncQueue.getProvisioner(provisionerId) # -> result
await asyncQueue.getProvisioner(provisionerId='value') # -> result

Update a provisioner

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.

Takes the following arguments:

• provisionerId

Required input schema

Required output schema

# Sync calls
queue.declareProvisioner(provisionerId, payload) # -> result`
queue.declareProvisioner(payload, provisionerId='value') # -> result
# Async call
await asyncQueue.declareProvisioner(provisionerId, payload) # -> result
await asyncQueue.declareProvisioner(payload, provisionerId='value') # -> result

Get Number of Pending Tasks

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.

Takes the following arguments:

• provisionerId
• workerType

Required output schema

# Sync calls
queue.pendingTasks(provisionerId, workerType) # -> result`
queue.pendingTasks(provisionerId='value', workerType='value') # -> result
# Async call
await asyncQueue.pendingTasks(provisionerId, workerType) # -> result
await asyncQueue.pendingTasks(provisionerId='value', workerType='value') # -> result

Get a list of all active worker-types

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.

Takes the following arguments:

• provisionerId

Required output schema

# Sync calls
queue.listWorkerTypes(provisionerId) # -> result`
queue.listWorkerTypes(provisionerId='value') # -> result
# Async call
await asyncQueue.listWorkerTypes(provisionerId) # -> result
await asyncQueue.listWorkerTypes(provisionerId='value') # -> result

Get a worker-type

Get a worker-type from a provisioner.

Takes the following arguments:

• provisionerId
• workerType

Required output schema

# Sync calls
queue.getWorkerType(provisionerId, workerType) # -> result`
queue.getWorkerType(provisionerId='value', workerType='value') # -> result
# Async call
await asyncQueue.getWorkerType(provisionerId, workerType) # -> result
await asyncQueue.getWorkerType(provisionerId='value', workerType='value') # -> result

Update a worker-type

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.

Takes the following arguments:

• provisionerId
• workerType

Required input schema

Required output schema

# Sync calls
queue.declareWorkerType(provisionerId, workerType, payload) # -> result`
queue.declareWorkerType(payload, provisionerId='value', workerType='value') # -> result
# Async call
await asyncQueue.declareWorkerType(provisionerId, workerType, payload) # -> result
await asyncQueue.declareWorkerType(payload, provisionerId='value', workerType='value') # -> result

Get a list of all active workers of a workerType

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.

Takes the following arguments:

• provisionerId
• workerType

Required output schema

# Sync calls
queue.listWorkers(provisionerId, workerType) # -> result`
queue.listWorkers(provisionerId='value', workerType='value') # -> result
# Async call
await asyncQueue.listWorkers(provisionerId, workerType) # -> result
await asyncQueue.listWorkers(provisionerId='value', workerType='value') # -> result

Get a worker-type

Get a worker from a worker-type.

Takes the following arguments:

• provisionerId
• workerType
• workerGroup
• workerId

Required output schema

# Sync calls
queue.getWorker(provisionerId, workerType, workerGroup, workerId) # -> result`
queue.getWorker(provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result
# Async call
await asyncQueue.getWorker(provisionerId, workerType, workerGroup, workerId) # -> result
await asyncQueue.getWorker(provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result

Quarantine a worker

Quarantine a worker

Takes the following arguments:

• provisionerId
• workerType
• workerGroup
• workerId

Required input schema

Required output schema

# Sync calls
queue.quarantineWorker(provisionerId, workerType, workerGroup, workerId, payload) # -> result`
queue.quarantineWorker(payload, provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result
# Async call
await asyncQueue.quarantineWorker(provisionerId, workerType, workerGroup, workerId, payload) # -> result
await asyncQueue.quarantineWorker(payload, provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result

Declare a worker

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.

Takes the following arguments:

• provisionerId
• workerType
• workerGroup
• workerId

Required input schema

Required output schema

# Sync calls
queue.declareWorker(provisionerId, workerType, workerGroup, workerId, payload) # -> result`
queue.declareWorker(payload, provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result
# Async call
await asyncQueue.declareWorker(provisionerId, workerType, workerGroup, workerId, payload) # -> result
await asyncQueue.declareWorker(payload, provisionerId='value', workerType='value', workerGroup='value', workerId='value') # -> result

Exchanges in taskcluster.QueueEvents

// Create QueueEvents client instance
import taskcluster
queueEvents = taskcluster.QueueEvents(options)

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 AMQP exchanges offered by the queue, which allows third-party listeners to monitor tasks as they progress to resolution. These exchanges targets the following audience:

• Schedulers, who takes action after tasks are completed,
• Workers, who wants to listen for new or canceled tasks (optional),
• Tools, that wants to update their view as task progress.

You'll notice that all the exchanges in the document shares the same routing key pattern. This makes it very easy to bind to all messages about a certain kind tasks.

Task specific routes, a task can define a task specific route using the task.routes property. See task creation documentation for details on permissions required to provide task specific routes. If a task has the entry 'notify.by-email' in as task specific route defined in task.routes all messages about this task will be CC'ed with the routing-key 'route.notify.by-email'.

These routes will always be prefixed route., so that cannot interfere with the primary routing key as documented here. Notice that the primary routing key is always prefixed primary.. This is ensured in the routing key reference, so API clients will do this automatically.

Please, note that the way RabbitMQ works, the message will only arrive in your queue once, even though you may have bound to the exchange with multiple routing key patterns that matches more of the CC'ed routing routing keys.

Delivery guarantees, most operations on the queue are idempotent, which means that if repeated with the same arguments then the requests will ensure completion of the operation and return the same response. This is useful if the server crashes or the TCP connection breaks, but when re-executing an idempotent operation, the queue will also resend any related AMQP messages. Hence, messages may be repeated.

This shouldn't be much of a problem, as the best you can achieve using confirm messages with AMQP is at-least-once delivery semantics. Hence, this only prevents you from obtaining at-most-once delivery semantics.

Remark, some message generated by timeouts maybe dropped if the server crashes at wrong time. Ideally, we'll address this in the future. For now we suggest you ignore this corner case, and notify us if this corner case is of concern to you.

Task Defined Messages

• queueEvents.taskDefined(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Pending Messages

• queueEvents.taskPending(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId is required Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Running Messages

• queueEvents.taskRunning(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId is required Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup is required Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId is required Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Artifact Creation Messages

• queueEvents.artifactCreated(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId is required Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup is required Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId is required Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Completed Messages

• queueEvents.taskCompleted(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId is required Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup is required Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId is required Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Failed Messages

• queueEvents.taskFailed(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Exception Messages

• queueEvents.taskException(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskId is required Description: taskId for the task this message concerns
  • runId Description: runId of latest run for the task, _ if no run is exists for the task.
  • workerGroup Description: workerGroup of latest run for the task, _ if no run is exists for the task.
  • workerId Description: workerId of latest run for the task, _ if no run is exists for the task.
  • provisionerId is required Description: provisionerId this task is targeted at.
  • workerType is required Description: workerType this task must run on.
  • schedulerId is required Description: schedulerId this task was created by.
  • taskGroupId is required Description: taskGroupId this task was created in.
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Task Group Resolved Messages

• queueEvents.taskGroupResolved(routingKeyPattern) -> routingKey
  • routingKeyKind is constant of primary is required Description: Identifier for the routing-key kind. This is always 'primary' for the formalized routing key.
  • taskGroupId is required Description: taskGroupId for the task-group this message concerns
  • schedulerId is required Description: schedulerId for the task-group this message concerns
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.

Methods in taskcluster.Secrets

import asyncio # Only for async 
// Create Secrets client instance
import taskcluster
import taskcluster.aio

secrets = taskcluster.Secrets(options)
# Below only for async instances, assume already in coroutine
loop = asyncio.get_event_loop()
session = taskcluster.aio.createSession(loop=loop)
asyncSecrets = taskcluster.aio.Secrets(options, session=session)

The secrets service provides a simple key/value store for small bits of secret data. Access is limited by scopes, so values can be considered secret from those who do not have the relevant scopes.

Secrets also have an expiration date, and once a secret has expired it can no longer be read. This is useful for short-term secrets such as a temporary service credential or a one-time signing key.

Ping Server

Respond without doing anything. This endpoint is used to check that the service is up.

# Sync calls
secrets.ping() # -> None`
# Async call
await asyncSecrets.ping() # -> None

Set Secret

Set the secret associated with some key. If the secret already exists, it is updated instead.

Takes the following arguments:

• name

Required input schema

# Sync calls
secrets.set(name, payload) # -> None`
secrets.set(payload, name='value') # -> None
# Async call
await asyncSecrets.set(name, payload) # -> None
await asyncSecrets.set(payload, name='value') # -> None

Delete Secret

Delete the secret associated with some key.

Takes the following arguments:

• name

# Sync calls
secrets.remove(name) # -> None`
secrets.remove(name='value') # -> None
# Async call
await asyncSecrets.remove(name) # -> None
await asyncSecrets.remove(name='value') # -> None

Read Secret

Read the secret associated with some key. If the secret has recently expired, the response code 410 is returned. If the caller lacks the scope necessary to get the secret, the call will fail with a 403 code regardless of whether the secret exists.

Takes the following arguments:

• name

Required output schema

# Sync calls
secrets.get(name) # -> result`
secrets.get(name='value') # -> result
# Async call
await asyncSecrets.get(name) # -> result
await asyncSecrets.get(name='value') # -> result

List Secrets

List the names of all secrets.

By default this end-point will try to return up to 1000 secret names 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.

Required output schema

# Sync calls
secrets.list() # -> result`
# Async call
await asyncSecrets.list() # -> result

Exchanges in taskcluster.TreeherderEvents

// Create TreeherderEvents client instance
import taskcluster
treeherderEvents = taskcluster.TreeherderEvents(options)

The taskcluster-treeherder service is responsible for processing task events published by TaskCluster Queue and producing job messages that are consumable by Treeherder.

This exchange provides that job messages to be consumed by any queue that attached to the exchange. This could be a production Treeheder instance, a local development environment, or a custom dashboard.

Job Messages

• treeherderEvents.jobs(routingKeyPattern) -> routingKey
  • destination is required Description: destination
  • project is required Description: project
  • reserved Description: Space reserved for future routing-key entries, you should always match this entry with #. As automatically done by our tooling, if not specified.