Skip to content
Ona API Reference
Ona Docs
API Reference
Environments
Automations
Tasks

ListTasks

client.environments.automations.tasks.list(TaskListParams { token, pageSize, filter, pagination } params, RequestOptionsoptions?): TasksPage<Task { id, dependsOn, environmentId, 2 more } >
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
ParametersExpand Collapse
params: TaskListParams { token, pageSize, filter, pagination }
token?: string

Query param

pageSize?: number

Query param

maximum100
minimum0
filter?: Filter

Body param: filter contains the filter options for listing tasks

environmentIds?: Array<string>

environment_ids filters the response to only tasks of these environments

references?: Array<string>

references filters the response to only services with these references

taskIds?: Array<string>

task_ids filters the response to only tasks with these IDs

ReturnsExpand Collapse
Task { id, dependsOn, environmentId, 2 more }
id: string
formatuuid
dependsOn?: Array<string>

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

environmentId?: string
formatuuid
metadata?: TaskMetadata { createdAt, creator, description, 3 more }
createdAt?: string

created_at is the time the task was created.

formatdate-time
creator?: Subject { id, principal }

creator describes the principal who created the task.

id?: string

id is the UUID of the subject

formatuuid
principal?: 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?: string

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

name?: 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?: 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?: Array<AutomationTrigger { beforeSnapshot, manual, postDevcontainerStart, 3 more } >

triggered_by is a list of trigger that start the task.

beforeSnapshot?: boolean
manual?: boolean
postDevcontainerStart?: boolean
postEnvironmentStart?: boolean
postMachineStart?: boolean
prebuild?: boolean
spec?: TaskSpec { command, env, prebuildRequiresSuccess, runsOn }
command?: string

command contains the command the task should execute

env?: Array<EnvironmentVariableItem { name, value, valueFrom } >

env specifies environment variables for the task.

name?: string

name is the environment variable name.

minLength1
value?: string

value is a literal string value.

valueFrom?: EnvironmentVariableSource { secretRef }

value_from specifies a source for the value.

secretRef: SecretRef { id }

secret_ref references a secret by ID.

id?: string

id is the UUID of the secret to reference.

formatuuid
prebuildRequiresSuccess?: 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?: RunsOn { docker, machine }

runs_on specifies the environment the task should run on.

docker?: Docker { environment, image }
environment?: Array<string>
image?: string
minLength1
machine?: unknown

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

ListTasks

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const task of client.environments.automations.tasks.list({
  filter: { references: ['build', 'test'] },
  pagination: { pageSize: 20 },
})) {
  console.log(task.id);
}
{
  "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": {}
        }
      }
    }
  ]
}