Update Workflow

Unary · Workflows Updates a workflow’s configuration using full replacement semantics. Update Behavior:

All provided fields completely replace existing values
Optional fields that are not provided remain unchanged
Complex fields (triggers, action) are replaced entirely, not merged
To remove optional fields, explicitly set them to empty/default values

Use this method to:

Modify workflow settings
Update triggers and actions
Change execution limits
Update workflow steps

Examples

Update workflow name: Changes the workflow’s display name.

workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "Updated Workflow Name"

Replace all triggers: Completely replaces the workflow’s trigger configuration.

workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
triggers:
  - manual: {}
    context:
      projects:
        projectIds: ["new-project-id"]

Update execution limits: Completely replaces the workflow’s action configuration.

workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
action:
  limits:
    maxParallel: 10
    maxTotal: 100
  steps:
    - task:
        command: "npm test"

Endpoint

POST /api/gitpod.v1.WorkflowService/UpdateWorkflow

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.WorkflowService/UpdateWorkflow" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "workflowId": "<workflow-id>"
}'

import gitpod.v1.workflow_pb2 as workflow_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = workflow_pb2.UpdateWorkflowRequest(
    workflow_id="<workflow-id>",
)
response = ona.services.workflow.update_workflow(request)
print(response)

import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateWorkflowRequestSchema } from "@gitpod/sdk/gitpod/v1/workflow_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(UpdateWorkflowRequestSchema, {
    workflowId: "<workflow-id>",
  });
  const response = await ona.services.workflow.updateWorkflow(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.UpdateWorkflowRequest{
		WorkflowId: "<workflow-id>",
	})
	response, err := ona.Services.Workflow.UpdateWorkflow(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "workflowId": "<workflow-id>"
}

Request

gitpod.v1.UpdateWorkflowRequest UpdateWorkflowRequest updates a workflow’s configuration.

Field	Type	Required	Description
`workflowId`	string	No	Constraints: `string.uuid=true`.
`name`	string	No	Constraints: `cel.expression=size(this) >= 1 && size(this) <= 80, cel.id=name_length, cel.message=Name must be between 1 and 80 characters`.
`description`	string	No	Constraints: `cel.expression=size(this) <= 500, cel.id=description_length, cel.message=Description must be at most 500 characters`.
`triggers`	array of WorkflowTrigger	No	Constraints: `cel.expression=size(this) <= 10, cel.id=triggers_count, cel.message=Automation can have at most 10 triggers`.
`action`	WorkflowAction	No
`report`	WorkflowAction	No
`executor`	Subject	No
`disabled`	boolean	No	When set, enables or disables the workflow. A disabled workflow will not be triggered by any automatic trigger and manual starts are rejected.
`agentId`	string	No	Agent that runs this workflow. When empty, the agent is resolved at run time (defaults to the Ona agent).
`codexSettings`	CodexSettings	No	Codex app agent settings. Only meaningful when agent_id refers to the Codex app agent.

Response

gitpod.v1.UpdateWorkflowResponse

Field	Type	Required	Description
`workflow`	Workflow	No

CodexSettings

CodexSettings contains settings consumed only by the Codex app agent.gitpod.v1.CodexSettings

Field	Type	Required	Description
`model`	CodexOpenAIModel	No	Constraints: `enum.defined_only=true`.
`reasoningEffort`	CodexReasoningEffort	No	Constraints: `enum.defined_only=true`.
`serviceTier`	CodexServiceTier	No	Constraints: `enum.defined_only=true`.

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

Workflow

Workflow represents a workflow configuration.gitpod.v1.Workflow

Field	Type	Required	Description
`id`	string	No	Constraints: `string.uuid=true`.
`metadata`	Metadata	No
`spec`	Spec	No
`webhookUrl`	string	No	Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks

Metadata

WorkflowMetadata contains workflow metadata.gitpod.v1.Workflow.Metadata

Field	Type	Required	Description
`name`	string	No	Constraints: `string.max_len=80, string.min_len=1`.
`description`	string	No	Constraints: `string.max_len=500`.
`creator`	Subject	No
`executor`	Subject	No
`createdAt`	RFC 3339 timestamp	No
`updatedAt`	RFC 3339 timestamp	No

Spec

gitpod.v1.Workflow.Spec

Field	Type	Required	Description
`triggers`	array of WorkflowTrigger	No
`action`	WorkflowAction	No
`report`	WorkflowAction	No
`deleting`	boolean	No	Marks workflow as pending deletion
`disabled`	boolean	No	When true, the workflow will not be triggered by any automatic trigger (cron, webhook, pull request). Manual starts via StartWorkflow are also rejected while disabled.
`agentId`	string	No	Agent that runs this workflow. When empty, the agent is resolved at run time (defaults to the Ona agent), preserving behavior for workflows created before agent selection existed.
`codexSettings`	CodexSettings	No	Codex app agent settings (model, reasoning effort, service tier). Only meaningful when agent_id refers to the Codex app agent.

WorkflowAction

WorkflowAction defines the actions to be executed in a workflow.gitpod.v1.WorkflowAction

Field	Type	Required	Description
`limits`	Limits	Yes	Constraints: `required=true`.
`steps`	array of WorkflowStep	No	Constraints: `cel.expression=size(this) >= 1 && size(this) <= 50, cel.id=steps_count, cel.message=Automation must have between 1 and 50 steps`.

Limits

Limits defines execution limits for workflow actions.gitpod.v1.WorkflowAction.Limits

Field	Type	Required	Description
`maxParallel`	integer	No	Constraints: `cel.expression=this >= 1 && this <= 25, cel.id=max_parallel_range, cel.message=Maximum parallel actions must be between 1 and 25`.
`maxTotal`	integer	No	Constraints: `cel.expression=this >= 1 && this <= 100, cel.id=max_total_range, cel.message=Maximum total actions must be between 1 and 100`.
`perExecution`	PerExecution	No

WorkflowStep

WorkflowStep defines a single step in a workflow action.gitpod.v1.WorkflowStep

Field	Type	Required
`task`	Task	No
`agent`	Agent	No
`pullRequest`	PullRequest	No
`report`	Report	No

WorkflowTrigger

WorkflowTrigger defines when a workflow should be executed.Each trigger type defines a specific condition that will cause the workflow to execute:

Manual: Triggered explicitly by user action via StartWorkflow RPC
Time: Triggered automatically based on cron schedule
PullRequest: Triggered automatically when specified PR events occur

Trigger Semantics:

Each trigger instance can create multiple workflow executions
Multiple triggers of the same workflow can fire simultaneously
Each trigger execution is independent and tracked separately
Triggers are evaluated in the context specified by WorkflowTriggerContext

gitpod.v1.WorkflowTrigger

Field	Type	Required	Description
`manual`	Manual	No
`time`	Time	No
`pullRequest`	PullRequest	No
`context`	WorkflowTriggerContext	Yes	Constraints: `required=true`.

Manual

Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed.gitpod.v1.WorkflowTrigger.ManualThis message has no fields.

PullRequest

Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context.gitpod.v1.WorkflowTrigger.PullRequest

Field	Type	Required	Description
`events`	array of PullRequestEvent	No
`webhookId`	string	No	webhook_id is the optional ID of a webhook that this trigger is bound to. When set, the trigger will be activated when the webhook receives events. This allows multiple workflows to share a single webhook endpoint. Constraints: `string.uuid=true`.
`integrationId`	string	No	integration_id is the optional ID of an integration that acts as the source of webhook events. When set, the trigger will be activated when the webhook receives events. Constraints: `string.uuid=true`.

Time

Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday).gitpod.v1.WorkflowTrigger.Time

Field	Type	Required	Description
`cronExpression`	string	No	Constraints: `cel.expression=size(this) >= 1 && size(this) <= 100, cel.id=cron_expression_length, cel.message=Cron expression must be between 1 and 100 characters`.

WorkflowTriggerContext

WorkflowTriggerContext defines the context in which a workflow should run.Context determines where and how the workflow executes:

Projects: Execute in specific project environments
Repositories: Execute in environments created from repository URLs
Agent: Execute in agent-managed environments with custom prompts
FromTrigger: Use context derived from the trigger event (PR-specific)

Context Usage by Trigger Type:

Manual: Can use any context type
Time: Typically uses Projects or Repositories context
PullRequest: Can use any context, FromTrigger uses PR repository context
Incident: Typically uses Projects or Repositories context (no inherent repo context)

gitpod.v1.WorkflowTriggerContext

Field	Type	Required
`projects`	Projects	No
`repositories`	Repositories	No
`agent`	Agent	No
`fromTrigger`	FromTrigger	No

CodexOpenAIModel

CodexOpenAIModel is the static allowlist of concrete OpenAI models that the Codex app runtime can select through Ona’s Codex picker.

Value	Number	Description
`CODEX_OPEN_AI_MODEL_UNSPECIFIED`	0
`CODEX_OPEN_AI_MODEL_GPT_5_5`	1
`CODEX_OPEN_AI_MODEL_GPT_5_4`	2
`CODEX_OPEN_AI_MODEL_GPT_5_4_MINI`	3	Deprecated.
`CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX`	4	Deprecated.
`CODEX_OPEN_AI_MODEL_GPT_5_3_CODEX_SPARK`	5	Deprecated.
`CODEX_OPEN_AI_MODEL_GPT_5_2`	6	Deprecated.
`CODEX_OPEN_AI_MODEL_GPT_5_6_SOL`	7
`CODEX_OPEN_AI_MODEL_GPT_5_6_TERRA`	8
`CODEX_OPEN_AI_MODEL_GPT_5_6_LUNA`	9

CodexReasoningEffort

CodexReasoningEffort is the static allowlist of reasoning efforts supported by the Codex app runtime.

Value	Number	Description
`CODEX_REASONING_EFFORT_UNSPECIFIED`	0
`CODEX_REASONING_EFFORT_LOW`	1
`CODEX_REASONING_EFFORT_MEDIUM`	2
`CODEX_REASONING_EFFORT_HIGH`	3
`CODEX_REASONING_EFFORT_EXTRA_HIGH`	4
`CODEX_REASONING_EFFORT_MAX`	5
`CODEX_REASONING_EFFORT_ULTRA`	6

CodexServiceTier

CodexServiceTier is the static allowlist of service tiers supported by the Codex app runtime.

Value	Number	Description
`CODEX_SERVICE_TIER_UNSPECIFIED`	0
`CODEX_SERVICE_TIER_FAST`	1

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

PullRequestEvent

WorkflowPREvent defines pull request events that can trigger workflows.

Value	Number	Description
`PULL_REQUEST_EVENT_UNSPECIFIED`	0
`PULL_REQUEST_EVENT_OPENED`	1
`PULL_REQUEST_EVENT_UPDATED`	2
`PULL_REQUEST_EVENT_APPROVED`	3
`PULL_REQUEST_EVENT_MERGED`	4
`PULL_REQUEST_EVENT_CLOSED`	5
`PULL_REQUEST_EVENT_READY_FOR_REVIEW`	6
`PULL_REQUEST_EVENT_REVIEW_REQUESTED`	7

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