> ## 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. # Update Workflow > Updates a workflow's configuration using full replacement semantics. `Unary` ยท [`Workflows`](/docs/api-reference/generated/workflow/overview) 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. ```yaml theme={null} workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" name: "Updated Workflow Name" ``` * Replace all triggers: Completely replaces the workflow's trigger configuration. ```yaml theme={null} workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" triggers: - manual: {} context: projects: projectIds: ["new-project-id"] ``` * Update execution limits: Completely replaces the workflow's action configuration. ```yaml theme={null} workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" action: limits: maxParallel: 10 maxTotal: 100 steps: - task: command: "npm test" ``` ## Endpoint ```text theme={null} POST /api/gitpod.v1.WorkflowService/UpdateWorkflow ``` 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.WorkflowService/UpdateWorkflow" \ --header "Authorization: Bearer $ONA_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "workflowId": "" }' ``` ```python Python theme={null} 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="", ) response = ona.services.workflow.update_workflow(request) print(response) ``` ```typescript TypeScript theme={null} 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: "", }); const response = await ona.services.workflow.updateWorkflow(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.UpdateWorkflowRequest{ WorkflowId: "", }) response, err := ona.Services.Workflow.UpdateWorkflow(context.Background(), request) if err != nil { log.Fatal(err) } fmt.Println(response.Msg) } ``` ```json Request body theme={null} { "workflowId": "" } ``` ## 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](#type-gitpod-v1-workflow-trigger) | No | Constraints: `cel.expression=size(this) <= 10, cel.id=triggers_count, cel.message=Automation can have at most 10 triggers`. | | `action` | [WorkflowAction](#type-gitpod-v1-workflow-action) | No | | | `report` | [WorkflowAction](#type-gitpod-v1-workflow-action) | No | | | `executor` | [Subject](#type-gitpod-v1-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](#type-gitpod-v1-codex-settings) | 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](#type-gitpod-v1-workflow) | No | | ## Related types CodexSettings contains settings consumed only by the Codex app agent. `gitpod.v1.CodexSettings` | Field | Type | Required | Description | | ----------------- | -------------------------------------------------------------- | -------- | -------------------------------------- | | `model` | [CodexOpenAIModel](#enum-gitpod-v1-codex-open-ai-model) | No | Constraints: `enum.defined_only=true`. | | `reasoningEffort` | [CodexReasoningEffort](#enum-gitpod-v1-codex-reasoning-effort) | No | Constraints: `enum.defined_only=true`. | | `serviceTier` | [CodexServiceTier](#enum-gitpod-v1-codex-service-tier) | No | Constraints: `enum.defined_only=true`. | `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`. | Workflow represents a workflow configuration. `gitpod.v1.Workflow` | Field | Type | Required | Description | | ------------ | --------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `id` | string | No | Constraints: `string.uuid=true`. | | `metadata` | [Metadata](#type-gitpod-v1-workflow-metadata) | No | | | `spec` | [Spec](#type-gitpod-v1-workflow-spec) | No | | | `webhookUrl` | string | No | Webhook URL for triggering this workflow via HTTP POST Format: \{base\_url}/workflows/\{workflow\_id}/webhooks | 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 | | `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 defines the actions to be executed in a workflow. `gitpod.v1.WorkflowAction` | Field | Type | Required | Description | | -------- | ------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limits` | [Limits](#type-gitpod-v1-workflow-action-limits) | Yes | Constraints: `required=true`. | | `steps` | array of [WorkflowStep](#type-gitpod-v1-workflow-step) | 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 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 defines a single step in a workflow action. `gitpod.v1.WorkflowStep` | Field | Type | Required | Description | | ------------- | ----------- | -------- | ----------- | | `task` | Task | No | | | `agent` | Agent | No | | | `pullRequest` | PullRequest | No | | | `report` | Report | No | | 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](#type-gitpod-v1-workflow-trigger-manual) | No | | | `time` | [Time](#type-gitpod-v1-workflow-trigger-time) | No | | | `pullRequest` | [PullRequest](#type-gitpod-v1-workflow-trigger-pull-request) | No | | | `context` | [WorkflowTriggerContext](#type-gitpod-v1-workflow-trigger-context) | Yes | Constraints: `required=true`. | Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. `gitpod.v1.WorkflowTrigger.Manual` This message has no fields. 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](#enum-gitpod-v1-workflow-trigger-pull-request-event) | 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-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 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 | Description | | -------------- | ------------ | -------- | ----------- | | `projects` | Projects | No | | | `repositories` | Repositories | No | | | `agent` | Agent | No | | | `fromTrigger` | FromTrigger | No | | 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 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 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 | | | 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 | | 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 | |