> ## Documentation Index > Fetch the complete documentation index at: https://ona.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Task > Creates a new automation task. `Unary` ยท [`Environment Automations`](/docs/api-reference/generated/environment-automation/overview) 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. ```yaml theme={null} 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. ```yaml theme={null} 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"] ``` ## Endpoint ```text theme={null} POST /api/gitpod.v1.EnvironmentAutomationService/CreateTask ``` Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain. ## Request example ```bash cURL theme={null} export ONA_HOST=https://app.ona.com export ONA_API_KEY= curl --request POST \ --url "$ONA_HOST/api/gitpod.v1.EnvironmentAutomationService/CreateTask" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "environmentId": "" }' ``` ```python Python theme={null} import gitpod.v1.environment_automation_pb2 as environment_automation_pb2 from ona_sdk import create_client_from_env ona = create_client_from_env() request = environment_automation_pb2.CreateTaskRequest( environment_id="", ) response = ona.services.environment_automation.create_task(request) print(response) ``` ```typescript TypeScript theme={null} import { create } from "@bufbuild/protobuf"; import { createClientFromEnv } from "@gitpod/sdk"; import { CreateTaskRequestSchema } from "@gitpod/sdk/gitpod/v1/environment_automation_pb"; async function main() { const ona = createClientFromEnv(); const request = create(CreateTaskRequestSchema, { environmentId: "", }); const response = await ona.services.environmentAutomation.createTask(request); console.log(response); } main().catch(console.error); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "connectrpc.com/connect" "github.com/gitpod-io/gitpod-sdk-go/sdk" gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1" ) func main() { ona, err := sdk.NewFromEnv() if err != nil { log.Fatal(err) } request := connect.NewRequest(&gitpodpb.CreateTaskRequest{ EnvironmentId: "", }) response, err := ona.Services.EnvironmentAutomation.CreateTask(context.Background(), request) if err != nil { log.Fatal(err) } fmt.Println(response.Msg) } ``` ```json Request body theme={null} { "environmentId": "" } ``` ## Request `gitpod.v1.CreateTaskRequest` | Field | Type | Required | Description | | --------------- | --------------------------------------------- | -------- | ----------------------------------------------- | | `environmentId` | string | No | Constraints: `string.uuid=true`. | | `metadata` | [TaskMetadata](#type-gitpod-v1-task-metadata) | No | | | `spec` | [TaskSpec](#type-gitpod-v1-task-spec) | No | | | `dependsOn` | array of string | No | Constraints: `repeated.items.string.uuid=true`. | ## Response `gitpod.v1.CreateTaskResponse` | Field | Type | Required | Description | | ------ | ---------------------------- | -------- | ----------------------------- | | `task` | [Task](#type-gitpod-v1-task) | Yes | Constraints: `required=true`. | ## Related types An AutomationTrigger represents a trigger for an automation action. The `manual` field shows a start button in the UI for manually triggering the automation. The `post_machine_start` field indicates that the automation should be triggered after the machine has started, before the devcontainer is ready. This is used for machine-level services like security agents that need to start early. The `post_environment_start` field indicates that the automation should be triggered after the environment has started (devcontainer ready). The `post_devcontainer_start` field indicates that the automation should be triggered after the dev container has started. The `prebuild` field starts the automation during a prebuild of an environment. This phase does not have user secrets available. The `before_snapshot` field triggers the automation after all prebuild tasks complete but before the snapshot is taken. This is used for tasks that need to run last during prebuilds, such as IDE warmup. Note: The before\_snapshot trigger can only be used with tasks, not services. `gitpod.v1.AutomationTrigger` | Field | Type | Required | Description | | ----------------------- | ------- | -------- | ----------- | | `manual` | boolean | No | | | `postMachineStart` | boolean | No | | | `postEnvironmentStart` | boolean | No | | | `postDevcontainerStart` | boolean | No | | | `prebuild` | boolean | No | | | `beforeSnapshot` | boolean | No | | EnvironmentVariableItem represents an environment variable that can be set either from a literal value or from a secret reference. `gitpod.v1.EnvironmentVariableItem` | Field | Type | Required | Description | | ----------- | ------------------------- | -------- | ----------------------------------------------------------------------- | | `name` | string | No | name is the environment variable name. Constraints: `string.min_len=1`. | | `value` | string | No | value is a literal string value. | | `valueFrom` | EnvironmentVariableSource | No | value\_from specifies a source for the value. | `gitpod.v1.RunsOn` | Field | Type | Required | Description | | --------- | ------- | -------- | ----------- | | `docker` | Docker | No | | | `machine` | Machine | No | | `gitpod.v1.Subject` | Field | Type | Required | Description | | ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------- | | `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. | | `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. | `gitpod.v1.Task` | Field | Type | Required | Description | | --------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `id` | string | No | Constraints: `string.uuid=true`. | | `environmentId` | string | No | Constraints: `string.uuid=true`. | | `metadata` | [TaskMetadata](#type-gitpod-v1-task-metadata) | No | | | `spec` | [TaskSpec](#type-gitpod-v1-task-spec) | No | | | `dependsOn` | array of string | No | dependencies specifies the IDs of the automations this task depends on. Constraints: `repeated.items.string.uuid=true`. | `gitpod.v1.TaskMetadata` | Field | Type | Required | Description | | ------------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference` | string | No | 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). Constraints: `string.pattern=^[a-zA-Z0-9_-]{1,128}$`. | | `name` | string | No | 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. Constraints: `string.min_len=1`. | | `description` | string | No | description is a user-facing description for the task. It can be used to provide context and documentation for the task. | | `createdAt` | RFC 3339 timestamp | No | created\_at is the time the task was created. | | `creator` | [Subject](#type-gitpod-v1-subject) | No | creator describes the principal who created the task. | | `triggeredBy` | array of [AutomationTrigger](#type-gitpod-v1-automation-trigger) | No | triggered\_by is a list of trigger that start the task. | `gitpod.v1.TaskSpec` | Field | Type | Required | Description | | ------------------------- | ----------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command` | string | No | command contains the command the task should execute | | `runsOn` | [RunsOn](#type-gitpod-v1-runs-on) | No | runs\_on specifies the environment the task should run on. | | `env` | array of [EnvironmentVariableItem](#type-gitpod-v1-environment-variable-item) | No | env specifies environment variables for the task. | | `prebuildRequiresSuccess` | boolean | No | 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 recording a warning. Defaults to false (existing behavior: task failures produce warnings only). | | Value | Number | Description | | --------------------------- | -----: | ----------- | | `PRINCIPAL_UNSPECIFIED` | 0 | | | `PRINCIPAL_ACCOUNT` | 1 | | | `PRINCIPAL_USER` | 2 | | | `PRINCIPAL_RUNNER` | 3 | | | `PRINCIPAL_ENVIRONMENT` | 4 | | | `PRINCIPAL_SERVICE_ACCOUNT` | 5 | | | `PRINCIPAL_RUNNER_MANAGER` | 6 | |