ListTasks

POST/gitpod.v1.EnvironmentAutomationService/ListTasks

Lists automation tasks with optional filtering.

Use this method to:

View all tasks in an environment
Filter tasks by reference
Monitor task status

Examples

List environment tasks:

Shows all tasks for an environment.

filter:
  environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
pagination:
  pageSize: 20

Filter by reference:

Lists tasks matching specific references.

filter:
  references: ["build", "test"]
pagination:
  pageSize: 20

Query ParametersExpand Collapse

token: optional string

pageSize: optional number

maximum100

minimum0

Body ParametersJSONExpand Collapse

filter: optional object { environmentIds, references, taskIds }

filter contains the filter options for listing tasks

environmentIds: optional array of string

environment_ids filters the response to only tasks of these environments

references: optional array of string

references filters the response to only services with these references

taskIds: optional array of string

task_ids filters the response to only tasks with these IDs

pagination: optional object { token, pageSize }

pagination contains the pagination options for listing tasks

token: optional string

Token for the next set of results that was returned as next_token of a PaginationResponse

pageSize: optional number

Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.

formatint32

maximum100

ReturnsExpand Collapse

pagination: optional object { nextToken }

nextToken: optional string

Token passed for retrieving the next set of results. Empty if there are no more results

tasks: optional array of Task { id, dependsOn, environmentId, 2 more }

id: string

formatuuid

dependsOn: optional array of string

dependencies specifies the IDs of the automations this task depends on.

environmentId: optional string

formatuuid

metadata: optional TaskMetadata { createdAt, creator, description, 3 more }

createdAt: optional string

created_at is the time the task was created.

formatdate-time

creator: optional Subject { id, principal }

creator describes the principal who created the task.

id: optional string

id is the UUID of the subject

formatuuid

principal: optional Principal

Principal is the principal of the subject

One of the following:

"PRINCIPAL_UNSPECIFIED"

"PRINCIPAL_ACCOUNT"

"PRINCIPAL_USER"

"PRINCIPAL_RUNNER"

"PRINCIPAL_ENVIRONMENT"

"PRINCIPAL_SERVICE_ACCOUNT"

"PRINCIPAL_RUNNER_MANAGER"

description: optional string

description is a user-facing description for the task. It can be used to provide context and documentation for the task.

name: optional string

name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task.

minLength1

reference: optional string

reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI).

triggeredBy: optional array of AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more }

triggered_by is a list of trigger that start the task.

beforeSnapshot: optional boolean

manual: optional boolean

postDevcontainerStart: optional boolean

postEnvironmentStart: optional boolean

postMachineStart: optional boolean

prebuild: optional boolean

spec: optional TaskSpec { command, env, prebuildRequiresSuccess, runsOn }

command: optional string

command contains the command the task should execute

env: optional array of EnvironmentVariableItem { name, value, valueFrom }

env specifies environment variables for the task.

name: optional string

name is the environment variable name.

minLength1

value: optional string

value is a literal string value.

valueFrom: optional EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id: optional string

id is the UUID of the secret to reference.

formatuuid

prebuildRequiresSuccess: optional boolean

prebuild_requires_success controls whether a non-successful outcome of this task should fail the prebuild. When true and the task is triggered by a prebuild or before_snapshot trigger, any terminal phase other than SUCCEEDED (i.e. FAILED or STOPPED) will cause the prebuild to fail instead of just recording a warning. Defaults to false (existing behavior: task failures produce warnings only).

runsOn: optional RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker: optional object { environment, image }

environment: optional array of string

image: optional string

minLength1

machine: optional unknown

Machine runs the service/task directly on the VM/machine level.

ListTasks

curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/ListTasks \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "tasks": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "dependsOn": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "description": "description",
        "name": "x",
        "reference": "reference",
        "triggeredBy": [
          {
            "beforeSnapshot": true,
            "manual": true,
            "postDevcontainerStart": true,
            "postEnvironmentStart": true,
            "postMachineStart": true,
            "prebuild": true
          }
        ]
      },
      "spec": {
        "command": "command",
        "env": [
          {
            "name": "x",
            "value": "value",
            "valueFrom": {
              "secretRef": {
                "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
              }
            }
          }
        ],
        "prebuildRequiresSuccess": true,
        "runsOn": {
          "docker": {
            "environment": [
              "string"
            ],
            "image": "x"
          },
          "machine": {}
        }
      }
    }
  ]
}

Returns Examples

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "tasks": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "dependsOn": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "description": "description",
        "name": "x",
        "reference": "reference",
        "triggeredBy": [
          {
            "beforeSnapshot": true,
            "manual": true,
            "postDevcontainerStart": true,
            "postEnvironmentStart": true,
            "postMachineStart": true,
            "prebuild": true
          }
        ]
      },
      "spec": {
        "command": "command",
        "env": [
          {
            "name": "x",
            "value": "value",
            "valueFrom": {
              "secretRef": {
                "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
              }
            }
          }
        ],
        "prebuildRequiresSuccess": true,
        "runsOn": {
          "docker": {
            "environment": [
              "string"
            ],
            "image": "x"
          },
          "machine": {}
        }
      }
    }
  ]
}