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

StartTask

client.environments.automations.tasks.start(TaskStartParams { id } body, RequestOptionsoptions?): TaskStartResponse { taskExecution }
POST/gitpod.v1.EnvironmentAutomationService/StartTask

Starts a task by creating a new task execution. This call does not block until the task is started; the task will be started asynchronously.

Use this method to:

  • Trigger task execution
  • Run one-off tasks
  • Start scheduled tasks immediately

Examples

  • Start task:

    Creates a new execution of a task.

    id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
ParametersExpand Collapse
body: TaskStartParams { id }
id?: string
formatuuid
ReturnsExpand Collapse
TaskStartResponse { taskExecution }
taskExecution: TaskExecution { id, metadata, spec, status }
id: string
formatuuid
metadata?: TaskExecutionMetadata { completedAt, createdAt, creator, 4 more }
completedAt?: string

completed_at is the time the task execution was done.

formatdate-time
createdAt?: string

created_at is the time the task was created.

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

creator describes the principal who created/started the task run.

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"
environmentId?: string

environment_id is the ID of the environment in which the task run is executed.

formatuuid
startedAt?: string

started_at is the time the task execution actually started to run.

formatdate-time
startedBy?: string

started_by describes the trigger that started the task execution.

taskId?: string

task_id is the ID of the main task being executed.

formatuuid
spec?: TaskExecutionSpec { desiredPhase, plan }
desiredPhase?: TaskExecutionPhase

desired_phase is the phase the task execution should be in. Used to stop a running task execution early.

One of the following:
"TASK_EXECUTION_PHASE_UNSPECIFIED"
"TASK_EXECUTION_PHASE_PENDING"
"TASK_EXECUTION_PHASE_RUNNING"
"TASK_EXECUTION_PHASE_SUCCEEDED"
"TASK_EXECUTION_PHASE_FAILED"
"TASK_EXECUTION_PHASE_STOPPED"
plan?: Array<Plan>

plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed.

steps?: Array<Step>
id?: string

ID is the ID of the execution step

formatuuid
dependsOn?: Array<string>
label?: string
serviceId?: string
formatuuid
task?: Task { id, spec }
id?: string
formatuuid
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.

status?: TaskExecutionStatus { failureMessage, logUrl, phase, 2 more }
failureMessage?: string

failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state.

logUrl?: string

log_url is the URL to the logs of the task’s steps. If this is empty, the task either has no logs or has not yet started.

phase?: TaskExecutionPhase

the phase of a task execution represents the aggregated phase of all steps.

One of the following:
"TASK_EXECUTION_PHASE_UNSPECIFIED"
"TASK_EXECUTION_PHASE_PENDING"
"TASK_EXECUTION_PHASE_RUNNING"
"TASK_EXECUTION_PHASE_SUCCEEDED"
"TASK_EXECUTION_PHASE_FAILED"
"TASK_EXECUTION_PHASE_STOPPED"
statusVersion?: string

version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b.

steps?: Array<Step>

steps provides the status for each individual step of the task execution. If a step is missing it has not yet started.

id?: string

ID is the ID of the execution step

formatuuid
failureMessage?: string

failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state.

output?: Record<string, string>

output contains the output of the task execution. setting an output field to empty string will unset it.

phase?: TaskExecutionPhase

phase is the current phase of the execution step

One of the following:
"TASK_EXECUTION_PHASE_UNSPECIFIED"
"TASK_EXECUTION_PHASE_PENDING"
"TASK_EXECUTION_PHASE_RUNNING"
"TASK_EXECUTION_PHASE_SUCCEEDED"
"TASK_EXECUTION_PHASE_FAILED"
"TASK_EXECUTION_PHASE_STOPPED"

StartTask

import Gitpod from '@gitpod/sdk';

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

const response = await client.environments.automations.tasks.start({
  id: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
});

console.log(response.taskExecution);
{
  "taskExecution": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "metadata": {
      "completedAt": "2019-12-27T18:11:19.117Z",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "startedAt": "2019-12-27T18:11:19.117Z",
      "startedBy": "startedBy",
      "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    },
    "spec": {
      "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED",
      "plan": [
        {
          "steps": [
            {
              "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "dependsOn": [
                "string"
              ],
              "label": "label",
              "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "task": {
                "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
                "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": {}
                  }
                }
              }
            }
          ]
        }
      ]
    },
    "status": {
      "failureMessage": "failureMessage",
      "logUrl": "logUrl",
      "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED",
      "statusVersion": "statusVersion",
      "steps": [
        {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "failureMessage": "failureMessage",
          "output": {
            "foo": "string"
          },
          "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED"
        }
      ]
    }
  }
}
Returns Examples
{
  "taskExecution": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "metadata": {
      "completedAt": "2019-12-27T18:11:19.117Z",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "creator": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "principal": "PRINCIPAL_UNSPECIFIED"
      },
      "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "startedAt": "2019-12-27T18:11:19.117Z",
      "startedBy": "startedBy",
      "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
    },
    "spec": {
      "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED",
      "plan": [
        {
          "steps": [
            {
              "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "dependsOn": [
                "string"
              ],
              "label": "label",
              "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "task": {
                "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
                "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": {}
                  }
                }
              }
            }
          ]
        }
      ]
    },
    "status": {
      "failureMessage": "failureMessage",
      "logUrl": "logUrl",
      "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED",
      "statusVersion": "statusVersion",
      "steps": [
        {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "failureMessage": "failureMessage",
          "output": {
            "foo": "string"
          },
          "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED"
        }
      ]
    }
  }
}