> ## 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.
# Start Workflow
> Starts a workflow execution.
`Unary` ยท [`Workflows`](/docs/api-reference/generated/workflow/overview)
Starts a workflow execution.
Use this method to:
* Start workflow execution on demand
* Test workflow configurations
* Run workflows outside of automatic triggers
### Examples
* Start workflow:
Starts a workflow execution manually.
```yaml theme={null}
workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.WorkflowService/StartWorkflow
```
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/StartWorkflow" \
--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.StartWorkflowRequest(
workflow_id="",
)
response = ona.services.workflow.start_workflow(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { StartWorkflowRequestSchema } from "@gitpod/sdk/gitpod/v1/workflow_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(StartWorkflowRequestSchema, {
workflowId: "",
});
const response = await ona.services.workflow.startWorkflow(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.StartWorkflowRequest{
WorkflowId: "",
})
response, err := ona.Services.Workflow.StartWorkflow(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"workflowId": ""
}
```
## Request
`gitpod.v1.StartWorkflowRequest`
StartWorkflowRequest starts a workflow execution.
| Field | Type | Required | Description |
| ----------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workflowId` | string | No | Constraints: `string.uuid=true`. |
| `contextOverride` | [WorkflowTriggerContext](#type-gitpod-v1-workflow-trigger-context) | No | Optional context override for the execution. When provided, replaces the workflow's default trigger context. User must have appropriate permissions on the overridden resources. Supports Projects, Repositories, and Agent context types. FromTrigger context type is not supported for manual overrides. |
| `parameters` | map of string to string | No | Parameters to substitute into workflow steps using Go template syntax. Use \{\{ .Parameters.key\_name }} in templatable fields (task.command, agent.prompt, pull\_request.title/description/branch, trigger context agent.prompt). Keys must match pattern ^\[a-zA-Z\_]\[a-zA-Z0-9\_]\*$ Maximum 10 parameters allowed. Empty map is treated as no parameters provided. Constraints: `map.keys.string.pattern=^[a-zA-Z_][a-zA-Z0-9_]*$, map.max\_pairs=10\`. |
## Response
`gitpod.v1.StartWorkflowResponse`
| Field | Type | Required | Description |
| ------------------- | ------------------------------------------------------- | -------- | ----------- |
| `workflowExecution` | [WorkflowExecution](#type-gitpod-v1-workflow-execution) | No | |
## Related types
WorkflowExecution represents a workflow execution instance.
`gitpod.v1.WorkflowExecution`
| Field | Type | Required | Description |
| ---------- | ------------------------------------------------------- | -------- | -------------------------------- |
| `id` | string | No | Constraints: `string.uuid=true`. |
| `metadata` | [Metadata](#type-gitpod-v1-workflow-execution-metadata) | No | |
| `spec` | [Spec](#type-gitpod-v1-workflow-execution-spec) | No | |
| `status` | [Status](#type-gitpod-v1-workflow-execution-status) | No | |
WorkflowExecutionMetadata contains workflow execution metadata.
`gitpod.v1.WorkflowExecution.Metadata`
| Field | Type | Required | Description |
| ------------ | ------------------ | -------- | -------------------------------- |
| `workflowId` | string | No | Constraints: `string.uuid=true`. |
| `startedAt` | RFC 3339 timestamp | No | |
| `finishedAt` | RFC 3339 timestamp | No | |
| `creator` | Subject | No | |
| `executor` | Subject | No | |
WorkflowExecutionSpec contains the specification used for this execution.
`gitpod.v1.WorkflowExecution.Spec`
| Field | Type | Required | Description |
| -------------- | ------------------------------------------------------------------ | -------- | ----------- |
| `session` | string | No | |
| `desiredPhase` | [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | |
| `trigger` | WorkflowExecutionTrigger | No | |
| `action` | WorkflowAction | No | |
| `report` | WorkflowAction | No | |
WorkflowExecutionStatus contains the current status of a workflow execution.
`gitpod.v1.WorkflowExecution.Status`
| Field | Type | Required | Description |
| -------------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session` | string | No | |
| `phase` | [WorkflowExecutionPhase](#enum-gitpod-v1-workflow-execution-phase) | No | |
| `pendingActionCount` | integer | No | |
| `runningActionCount` | integer | No | |
| `failedActionCount` | integer | No | |
| `doneActionCount` | integer | No | |
| `stoppedActionCount` | integer | No | |
| `failureMessage` | string | No | **Deprecated.** FailureMessage summarises why the workflow execution failed to operate. If this is non-empty the workflow execution has failed to operate and will likely transition to a stopped state. Deprecated: Use failures instead for structured error information. |
| `warningMessage` | string | No | **Deprecated.** WarningMessage summarises why the workflow execution is in a warning state. If this is non-empty the workflow execution is in a warning state and likely does not match the users expectations. Deprecated: Use warnings field instead for structured warning information. |
| `failures` | array of WorkflowError | No | Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. |
| `warnings` | array of WorkflowError | No | Structured warnings about the workflow execution. Provides detailed warning codes and messages. |
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](#type-gitpod-v1-workflow-trigger-context-projects) | No | |
| `repositories` | [Repositories](#type-gitpod-v1-workflow-trigger-context-repositories) | No | |
| `agent` | [Agent](#type-gitpod-v1-workflow-trigger-context-agent) | No | |
| `fromTrigger` | [FromTrigger](#type-gitpod-v1-workflow-trigger-context-from-trigger) | No | |
Execute workflow in agent-managed environments.
Agent receives the specified prompt and manages execution context.
`gitpod.v1.WorkflowTriggerContext.Agent`
| Field | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt` | string | No | Constraints: `cel.expression=size(this) >= 1 && size(this) <= 20000, cel.id=agent_prompt_length, cel.message=Agent prompt must be between 1 and 20,000 characters`. |
Use context derived from the trigger event.
Currently only supported for PullRequest triggers - uses PR repository context.
`gitpod.v1.WorkflowTriggerContext.FromTrigger`
This message has no fields.
Execute workflow in specific project environments.
Creates environments for each specified project.
`gitpod.v1.WorkflowTriggerContext.Projects`
| Field | Type | Required | Description |
| ------------ | --------------- | -------- | ----------------------------------------------------------------------- |
| `projectIds` | array of string | No | Constraints: `repeated.items.string.uuid=true, repeated.max_items=500`. |
Execute workflow in environments created from repository URLs.
Supports both explicit repository URLs and search patterns.
`gitpod.v1.WorkflowTriggerContext.Repositories`
| Field | Type | Required | Description |
| -------------------- | ------------------ | -------- | -------------------------------- |
| `repositoryUrls` | RepositoryURLs | No | |
| `repoSelector` | RepositorySelector | No | |
| `environmentClassId` | string | No | Constraints: `string.uuid=true`. |
| Value | Number | Description |
| -------------------------------------- | -----: | ----------- |
| `WORKFLOW_EXECUTION_PHASE_UNSPECIFIED` | 0 | |
| `WORKFLOW_EXECUTION_PHASE_PENDING` | 1 | |
| `WORKFLOW_EXECUTION_PHASE_RUNNING` | 2 | |
| `WORKFLOW_EXECUTION_PHASE_STOPPING` | 3 | |
| `WORKFLOW_EXECUTION_PHASE_STOPPED` | 4 | |
| `WORKFLOW_EXECUTION_PHASE_DELETING` | 5 | |
| `WORKFLOW_EXECUTION_PHASE_DELETED` | 6 | |
| `WORKFLOW_EXECUTION_PHASE_COMPLETED` | 7 | |