StartTask

environments.automations.tasks.start() -> TaskStartResponse

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

id: Optional[str]

formatuuid

ReturnsExpand Collapse

class TaskStartResponse: …

task_execution: TaskExecution

id: str

formatuuid

metadata: Optional[TaskExecutionMetadata]

completed_at: Optional[datetime]

completed_at is the time the task execution was done.

formatdate-time

created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time

creator: Optional[Subject]

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

id: Optional[str]

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"

environment_id: Optional[str]

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

formatuuid

started_at: Optional[datetime]

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

formatdate-time

started_by: Optional[str]

started_by describes the trigger that started the task execution.

task_id: Optional[str]

task_id is the ID of the main task being executed.

formatuuid

spec: Optional[TaskExecutionSpec]

desired_phase: 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[List[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: Optional[List[PlanStep]]

id: Optional[str]

ID is the ID of the execution step

formatuuid

depends_on: Optional[List[str]]

label: Optional[str]

service_id: Optional[str]

formatuuid

task: Optional[PlanStepTask]

id: Optional[str]

formatuuid

spec: Optional[TaskSpec]

command: Optional[str]

command contains the command the task should execute

env: Optional[List[EnvironmentVariableItem]]

env specifies environment variables for the task.

name: Optional[str]

name is the environment variable name.

minLength1

value: Optional[str]

value is a literal string value.

value_from: Optional[EnvironmentVariableSource]

value_from specifies a source for the value.

secret_ref: SecretRef

secret_ref references a secret by ID.

id: Optional[str]

id is the UUID of the secret to reference.

formatuuid

prebuild_requires_success: Optional[bool]

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

runs_on: Optional[RunsOn]

runs_on specifies the environment the task should run on.

docker: Optional[Docker]

environment: Optional[List[str]]

image: Optional[str]

minLength1

machine: Optional[object]

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

status: Optional[TaskExecutionStatus]

failure_message: Optional[str]

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.

log_url: Optional[str]

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"

status_version: Optional[str]

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[List[Step]]

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

id: Optional[str]

ID is the ID of the execution step

formatuuid

failure_message: Optional[str]

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[Dict[str, str]]

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

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
response = client.environments.automations.tasks.start(
    id="d2c94c27-3b76-4a42-b88c-95a85e392c68",
)
print(response.task_execution)

{
  "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"
        }
      ]
    }
  }
}