StartTask

client.Environments.Automations.Tasks.Start(ctx, body) (*EnvironmentAutomationTaskStartResponse, error)

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 EnvironmentAutomationTaskStartParams

ID param.Field[string]Optional

formatuuid

ReturnsExpand Collapse

type EnvironmentAutomationTaskStartResponse struct{…}

TaskExecution TaskExecution

ID string

formatuuid

Metadata TaskExecutionMetadataOptional

CompletedAt TimeOptional

completed_at is the time the task execution was done.

formatdate-time

CreatedAt TimeOptional

created_at is the time the task was created.

formatdate-time

Creator SubjectOptional

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

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

EnvironmentID stringOptional

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

formatuuid

StartedAt TimeOptional

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

formatdate-time

StartedBy stringOptional

started_by describes the trigger that started the task execution.

TaskID stringOptional

task_id is the ID of the main task being executed.

formatuuid

Spec TaskExecutionSpecOptional

DesiredPhase TaskExecutionPhaseOptional

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

One of the following:

const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"

const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"

const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"

const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"

const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"

const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"

Plan []TaskExecutionSpecPlanOptional

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 []TaskExecutionSpecPlanStepOptional

ID stringOptional

ID is the ID of the execution step

formatuuid

DependsOn []stringOptional

Label stringOptional

ServiceID stringOptional

formatuuid

Task TaskExecutionSpecPlanStepsTaskOptional

ID stringOptional

formatuuid

Spec TaskSpecOptional

Command stringOptional

command contains the command the task should execute

Env []EnvironmentVariableItemOptional

env specifies environment variables for the task.

Name stringOptional

name is the environment variable name.

minLength1

Value stringOptional

value is a literal string value.

ValueFrom EnvironmentVariableSourceOptional

value_from specifies a source for the value.

SecretRef SecretRef

secret_ref references a secret by ID.

ID stringOptional

id is the UUID of the secret to reference.

formatuuid

PrebuildRequiresSuccess boolOptional

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 RunsOnOptional

runs_on specifies the environment the task should run on.

Docker RunsOnDockerOptional

Environment []stringOptional

Image stringOptional

minLength1

Machine unknownOptional

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

Status TaskExecutionStatusOptional

FailureMessage stringOptional

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 stringOptional

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 TaskExecutionPhaseOptional

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

One of the following:

const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"

const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"

const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"

const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"

const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"

const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"

StatusVersion stringOptional

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 []TaskExecutionStatusStepOptional

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

ID stringOptional

ID is the ID of the execution step

formatuuid

FailureMessage stringOptional

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 map[string, string]Optional

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

Phase TaskExecutionPhaseOptional

phase is the current phase of the execution step

One of the following:

const TaskExecutionPhaseUnspecified TaskExecutionPhase = "TASK_EXECUTION_PHASE_UNSPECIFIED"

const TaskExecutionPhasePending TaskExecutionPhase = "TASK_EXECUTION_PHASE_PENDING"

const TaskExecutionPhaseRunning TaskExecutionPhase = "TASK_EXECUTION_PHASE_RUNNING"

const TaskExecutionPhaseSucceeded TaskExecutionPhase = "TASK_EXECUTION_PHASE_SUCCEEDED"

const TaskExecutionPhaseFailed TaskExecutionPhase = "TASK_EXECUTION_PHASE_FAILED"

const TaskExecutionPhaseStopped TaskExecutionPhase = "TASK_EXECUTION_PHASE_STOPPED"

StartTask

package main

import (
  "context"
  "fmt"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Environments.Automations.Tasks.Start(context.TODO(), gitpod.EnvironmentAutomationTaskStartParams{
    ID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
        }
      ]
    }
  }
}