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

StartTask

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"
Body ParametersJSONExpand Collapse
id: optional string
formatuuid
ReturnsExpand Collapse
taskExecution: TaskExecution { id, metadata, spec, status }
id: string
formatuuid
metadata: optional TaskExecutionMetadata { completedAt, createdAt, creator, 4 more }
completedAt: optional string

completed_at is the time the task execution was done.

formatdate-time
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/started the task run.

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

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

formatuuid
startedAt: optional string

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

formatdate-time
startedBy: optional string

started_by describes the trigger that started the task execution.

taskId: optional string

task_id is the ID of the main task being executed.

formatuuid
spec: optional TaskExecutionSpec { desiredPhase, plan }
desiredPhase: optional 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: optional array of object { steps }

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: optional array of object { id, dependsOn, label, 2 more }
id: optional string

ID is the ID of the execution step

formatuuid
dependsOn: optional array of string
label: optional string
serviceId: optional string
formatuuid
task: optional object { id, spec }
id: optional string
formatuuid
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.

status: optional TaskExecutionStatus { failureMessage, logUrl, phase, 2 more }
failureMessage: optional 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: optional 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: optional 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: optional 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: optional array of object { id, failureMessage, output, phase }

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

id: optional string

ID is the ID of the execution step

formatuuid
failureMessage: optional 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: optional map[string]

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

phase: optional 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

curl https://app.gitpod.io/api/gitpod.v1.EnvironmentAutomationService/StartTask \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
{
  "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"
        }
      ]
    }
  }
}