> ## 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 Workflow

> Creates a new workflow with specified configuration.

`Unary` · [`Workflows`](https://ona.com/docs/api-reference/generated/workflow/overview)

Creates a new workflow with specified configuration.

Use this method to:

* Set up automations
* Configure workflow triggers
* Define workflow actions and steps
* Set execution limits and constraints

## Endpoint

```text theme={null}
POST /api/gitpod.v1.WorkflowService/CreateWorkflow
```

Send a Bearer token as described in [Authentication](https://ona.com/docs/api-reference.md#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=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.WorkflowService/CreateWorkflow" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "action": {
    "limits": {
      "maxParallel": 1
    }
  }
}'
```

```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.CreateWorkflowRequest(
    action=workflow_pb2.WorkflowAction(
        limits=workflow_pb2.WorkflowAction.Limits(
            max_parallel=1,
        ),
    ),
)
response = ona.services.workflow.create_workflow(request)
print(response)
```

```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { CreateWorkflowRequestSchema } from "@gitpod/sdk/gitpod/v1/workflow_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateWorkflowRequestSchema, {
    action: {
      limits: {
        maxParallel: 1,
      },
    },
  });
  const response = await ona.services.workflow.createWorkflow(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.CreateWorkflowRequest{
		Action: &gitpodpb.WorkflowAction{
			Limits: &gitpodpb.WorkflowAction_Limits{
				MaxParallel: 1,
			},
		},
	})
	response, err := ona.Services.Workflow.CreateWorkflow(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}
```

```json Request body theme={null}
{
  "action": {
    "limits": {
      "maxParallel": 1
    }
  }
}
```

## Request

`gitpod.v1.CreateWorkflowRequest`

CreateWorkflowRequest creates a new workflow.

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | No | Constraints: `cel.expression=size(this) >= 1 &amp;&amp; size(this) &lt;= 80, cel.id=name_length, cel.message=Name must be between 1 and 80 characters`. |
| `description` | string | No | Constraints: `cel.expression=size(this) &lt;= 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) >= 1 &amp;&amp; size(this) &lt;= 10, cel.id=triggers_count, cel.message=Automation must have between 1 and 10 triggers`. |
| `action` | [WorkflowAction](#type-gitpod-v1-workflow-action) | Yes | Constraints: `required=true`. |
| `report` | [WorkflowAction](#type-gitpod-v1-workflow-action) | No | |
| `executor` | [Subject](#type-gitpod-v1-subject) | No | Optional executor for the workflow. If not provided, defaults to the creator. Must be either the caller themselves or a service account. |
| `agentId` | string | No | Agent that runs this workflow. When empty, the agent is resolved at run time (defaults to the Ona agent). Constraints: `ignore=1, string.uuid=true`. |
| `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.CreateWorkflowResponse`

| Field | Type | Required | Description |
| - | - | - | - |
| `workflow` | [Workflow](#type-gitpod-v1-workflow) | No | |

## Related types

> [accordion] CodexSettings
>
> 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`. |

> [accordion] 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](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |

> [accordion] Workflow
>
> 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 |

> [accordion] 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 | |

> [accordion] 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. |

> [accordion] WorkflowAction
>
> 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 &amp;&amp; size(this) &lt;= 50, cel.id=steps_count, cel.message=Automation must have between 1 and 50 steps`. |

> [accordion] Limits
>
> Limits defines execution limits for workflow actions.
>
> `gitpod.v1.WorkflowAction.Limits`
>
> | Field | Type | Required | Description |
> | - | - | - | - |
> | `maxParallel` | integer | No | Constraints: `cel.expression=this >= 1 &amp;&amp; this &lt;= 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 &amp;&amp; this &lt;= 1000, cel.id=max_total_range, cel.message=Maximum total actions must be between 1 and 1000`. |
> | `perExecution` | PerExecution | No | |

> [accordion] WorkflowStep
>
> 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 | |

> [accordion] 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](#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`. |

> [accordion] Manual
>
> Manual trigger - executed when StartWorkflow RPC is called.
> No additional configuration needed.
>
> `gitpod.v1.WorkflowTrigger.Manual`
>
> This message has no fields.

> [accordion] 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](#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`. |

> [accordion] 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 &amp;&amp; size(this) &lt;= 100, cel.id=cron_expression_length, cel.message=Cron expression must be between 1 and 100 characters`. |

> [accordion] 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 | Description |
> | - | - | - | - |
> | `projects` | Projects | No | |
> | `repositories` | Repositories | No | |
> | `agent` | Agent | No | |
> | `fromTrigger` | FromTrigger | No | |

> [accordion] 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 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_ASTRA` | 10 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_SOL` | 11 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_LUNA` | 12 | |
> | `CODEX_OPEN_AI_MODEL_GPT_6_1_SOL` | 13 | |

> [accordion] 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 | |

> [accordion] 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 | |

> [accordion] 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 | |

> [accordion] 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 | |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.