API Reference

Environments

Automations

Tasks

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

CreateTask

environments.automations.tasks.create(TaskCreateParams**kwargs) -> TaskCreateResponse

POST/gitpod.v1.EnvironmentAutomationService/CreateTask

Creates a new automation task.

Use this method to:

• Define one-off or scheduled tasks
• Set up build or test automation
• Configure task dependencies
• Specify execution environments

Examples

• Create basic task:

  Creates a simple build task.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  metadata:
    reference: "build"
    name: "Build Project"
    description: "Builds the project artifacts"
    triggeredBy:
      - postEnvironmentStart: true
  spec:
    command: "npm run build"

• Create task with dependencies:

  Creates a task that depends on other services.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  metadata:
    reference: "test"
    name: "Run Tests"
    description: "Runs the test suite"
  spec:
    command: "npm test"
  dependsOn: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"]

ParametersExpand Collapse

depends_on: Optional[Sequence[str]]

environment_id: Optional[str]

formatuuid

metadata: Optional[TaskMetadata]

created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time

creator: Optional[Subject]

creator describes the principal who created the task.

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"

description: Optional[str]

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

name: Optional[str]

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: Optional[str]

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

triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the task.

before_snapshot: Optional[bool]

manual: Optional[bool]

post_devcontainer_start: Optional[bool]

post_environment_start: Optional[bool]

post_machine_start: Optional[bool]

prebuild: Optional[bool]

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.

ReturnsExpand Collapse

class TaskCreateResponse: …

task: Task

id: str

formatuuid

depends_on: Optional[List[str]]

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

environment_id: Optional[str]

formatuuid

metadata: Optional[TaskMetadata]

created_at: Optional[datetime]

created_at is the time the task was created.

formatdate-time

creator: Optional[Subject]

creator describes the principal who created the task.

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"

description: Optional[str]

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

name: Optional[str]

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: Optional[str]

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

triggered_by: Optional[List[AutomationTrigger]]

triggered_by is a list of trigger that start the task.

before_snapshot: Optional[bool]

manual: Optional[bool]

post_devcontainer_start: Optional[bool]

post_environment_start: Optional[bool]

post_machine_start: Optional[bool]

prebuild: Optional[bool]

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.

CreateTask

Python

HTTP

TypeScript

Python

Go

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
task = client.environments.automations.tasks.create(
    environment_id="07e03a28-65a5-4d98-b532-8ea67b188048",
    metadata={
        "description": "Builds the project artifacts",
        "name": "Build Project",
        "reference": "build",
        "triggered_by": [{
            "post_environment_start": True
        }],
    },
    spec={
        "command": "npm run build"
    },
)
print(task.task)

200 example

{
  "task": {
    "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

200 example

{
  "task": {
    "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": {}
      }
    }
  }
}