Create Task

Unary · Environment Automations 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"]

Endpoint

POST /api/gitpod.v1.EnvironmentAutomationService/CreateTask

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.EnvironmentAutomationService/CreateTask" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "environmentId": "<environment-id>"
}'

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="<environment-id>",
)
response = ona.services.environment_automation.create_task(request)
print(response)

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: "<environment-id>",
  });
  const response = await ona.services.environmentAutomation.createTask(request);
  console.log(response);
}

main().catch(console.error);

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: "<environment-id>",
	})
	response, err := ona.Services.EnvironmentAutomation.CreateTask(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "environmentId": "<environment-id>"
}

Request

gitpod.v1.CreateTaskRequest

Field	Type	Required	Description
`environmentId`	string	No	Constraints: `string.uuid=true`.
`metadata`	TaskMetadata	No
`spec`	TaskSpec	No
`dependsOn`	array of string	No	Constraints: `repeated.items.string.uuid=true`.

Response

gitpod.v1.CreateTaskResponse

Field	Type	Required	Description
`task`	Task	Yes	Constraints: `required=true`.

AutomationTrigger

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
`manual`	boolean	No
`postMachineStart`	boolean	No
`postEnvironmentStart`	boolean	No
`postDevcontainerStart`	boolean	No
`prebuild`	boolean	No
`beforeSnapshot`	boolean	No

EnvironmentVariableItem

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.

RunsOn

gitpod.v1.RunsOn

Field	Type	Required	Description
`docker`	Docker	No
`machine`	Machine	No

Subject

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	No	Principal is the principal of the subject Constraints: `enum.defined_only=true`.

Task

gitpod.v1.Task

Field	Type	Required	Description
`id`	string	No	Constraints: `string.uuid=true`.
`environmentId`	string	No	Constraints: `string.uuid=true`.
`metadata`	TaskMetadata	No
`spec`	TaskSpec	No
`dependsOn`	array of string	No	dependencies specifies the IDs of the automations this task depends on. Constraints: `repeated.items.string.uuid=true`.

TaskMetadata

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	No	creator describes the principal who created the task.
`triggeredBy`	array of AutomationTrigger	No	triggered_by is a list of trigger that start the task.

TaskSpec

gitpod.v1.TaskSpec

Field	Type	Required	Description
`command`	string	No	command contains the command the task should execute
`runsOn`	RunsOn	No	runs_on specifies the environment the task should run on.
`env`	array of EnvironmentVariableItem	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).

Principal

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

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types