Gitpod API Reference | Automations

Automations

automations

Methods

Cancel Workflow Execution -> unknown

post/gitpod.v1.WorkflowService/CancelWorkflowExecution

Cancels a running workflow execution.

Use this method to:

Stop long-running executions
Cancel failed executions
Manage resource usage

Examples

Cancel execution:

Stops a running workflow execution.

workflowExecutionId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

Cancel Workflow Execution Action -> unknown

post/gitpod.v1.WorkflowService/CancelWorkflowExecutionAction

Cancels a running workflow execution action.

Use this method to:

Stop long-running actions
Cancel failed actions
Manage resource usage

Examples

Cancel execution action:

Stops a running workflow execution action.

workflowExecutionActionId: "a1b2c3d4-5e6f-7890-abcd-ef1234567890"

Create Workflow -> { workflow }

post/gitpod.v1.WorkflowService/CreateWorkflow

Creates a new workflow with specified configuration.

Use this method to:

Set up automated workflows
Configure workflow triggers
Define workflow actions and steps
Set execution limits and constraints

Response fields

workflow:

Workflow

Optional

Workflow represents a workflow configuration.

Request example

curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/CreateWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "action": { "limits": {} } }'

200Example

{ "workflow": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "description": "description", "executor": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "name": "x", "updatedAt": "2019-12-27T18:11:19.117Z" }, "spec": { "action": { "limits": { "maxParallel": 0, "maxTotal": 0, "perExecution": { "maxTime": "+9125115.360s" } }, "steps": [ { "agent": { "prompt": "prompt" }, "pullRequest": { "branch": "branch", "description": "description", "draft": true, "title": "title" }, "report": { "outputs": [ { "acceptanceCriteria": "acceptanceCriteria", "boolean": {}, "command": "command", "float": { "max": 0, "min": 0 }, "integer": { "max": 0, "min": 0 }, "key": "key", "prompt": "prompt", "string": { "pattern": "pattern" }, "title": "title" } ] }, "task": { "command": "command" } } ] }, "deleting": true, "report": { "limits": { "maxParallel": 0, "maxTotal": 0, "perExecution": { "maxTime": "+9125115.360s" } }, "steps": [ { "agent": { "prompt": "prompt" }, "pullRequest": { "branch": "branch", "description": "description", "draft": true, "title": "title" }, "report": { "outputs": [ { "acceptanceCriteria": "acceptanceCriteria", "boolean": {}, "command": "command", "float": { "max": 0, "min": 0 }, "integer": { "max": 0, "min": 0 }, "key": "key", "prompt": "prompt", "string": { "pattern": "pattern" }, "title": "title" } ] }, "task": { "command": "command" } } ] }, "triggers": [ { "context": { "agent": { "prompt": "prompt" }, "fromTrigger": {}, "projects": { "projectIds": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ] }, "repositories": { "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "repoSelector": { "repoSearchString": "x", "scmHost": "x" }, "repositoryUrls": { "repoUrls": [ "x" ] } } }, "manual": {}, "pullRequest": { "events": [ "PULL_REQUEST_EVENT_UNSPECIFIED" ], "webhookId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "time": { "cronExpression": "cronExpression" } } ] }, "webhookUrl": "webhookUrl" } }

Delete Workflow -> unknown

post/gitpod.v1.WorkflowService/DeleteWorkflow

Deletes a workflow permanently.

Use this method to:

Remove unused workflows
Clean up test workflows
Delete obsolete configurations

Examples

Delete workflow:

Permanently removes a workflow.

workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"

List Workflows -> WorkflowsPage<

Workflow

post/gitpod.v1.WorkflowService/ListWorkflows

ListWorkflows

List Workflow Execution Actions -> WorkflowExecutionActionsPage<

WorkflowExecutionAction

post/gitpod.v1.WorkflowService/ListWorkflowExecutionActions

Lists workflow execution actions with optional filtering.

Use this method to:

Monitor individual action execution status
Debug action failures
Track resource usage per action

Examples

List execution actions for workflow execution:

Shows all execution actions for a specific workflow execution.
```
filter: workflowExecutionIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 20 
```

List Workflow Execution Outputs -> OutputsPage<{ actionId, values }>

post/gitpod.v1.WorkflowService/ListWorkflowExecutionOutputs

Lists outputs produced by workflow execution actions.

Use this method to:

Retrieve test results, coverage metrics, or other structured data from executions
Aggregate outputs across multiple workflow executions
Build dashboards or reports from execution data

Examples

List outputs for a workflow execution:

Retrieves all outputs produced by actions in the specified execution.
```
filter: workflowExecutionIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 50 
```

List Workflow Executions -> WorkflowExecutionsPage<

WorkflowExecution

post/gitpod.v1.WorkflowService/ListWorkflowExecutions

Lists workflow executions with optional filtering.

Use this method to:

Monitor workflow execution history
Track execution status
Debug workflow issues

Examples

List executions for workflow:

Shows all executions for a specific workflow.

filter: workflowIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 20

Get Workflow -> { workflow }

post/gitpod.v1.WorkflowService/GetWorkflow

Gets details about a specific workflow.

Use this method to:

View workflow configuration
Check workflow status
Get workflow metadata

Examples

Get workflow details:

Retrieves information about a specific workflow.
```
workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" 
```

Get Workflow Execution -> { workflowExecution }

post/gitpod.v1.WorkflowService/GetWorkflowExecution

Gets details about a specific workflow execution.

Use this method to:

Check execution status
View execution results
Monitor execution progress

Examples

Get execution details:

Retrieves information about a specific execution.
```
workflowExecutionId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" 
```

Get Workflow Execution Action -> { workflowExecutionAction }

post/gitpod.v1.WorkflowService/GetWorkflowExecutionAction

Gets details about a specific workflow execution action.

Use this method to:

Check execution action status
View execution action results
Monitor execution action progress

Examples

Get execution action details:

Retrieves information about a specific execution action.
```
workflowExecutionActionId: "a1b2c3d4-5e6f-7890-abcd-ef1234567890" 
```

Start Workflow -> { workflowExecution }

post/gitpod.v1.WorkflowService/StartWorkflow

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.

workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"

Update Workflow -> { workflow }

post/gitpod.v1.WorkflowService/UpdateWorkflow

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"

Domain types

AutomationCancelExecutionActionResponse = unknown

AutomationCancelExecutionResponse = unknown

AutomationCreateResponse = { workflow }

AutomationDeleteResponse = unknown

AutomationListExecutionOutputsResponse = { actionId, values }

AutomationRetrieveExecutionActionResponse = { workflowExecutionAction }

AutomationRetrieveExecutionResponse = { workflowExecution }

AutomationRetrieveResponse = { workflow }

AutomationStartExecutionResponse = { workflowExecution }

AutomationUpdateResponse = { workflow }

Workflow = { id, metadata, spec, 1 more... }

Workflow represents a workflow configuration.

WorkflowAction = { limits, steps }

WorkflowAction defines the actions to be executed in a workflow.

WorkflowExecution = { id, metadata, spec, 1 more... }

WorkflowExecution represents a workflow execution instance.

WorkflowExecutionAction = { id, metadata, spec, 1 more... }

WorkflowExecutionAction represents a workflow execution action instance.

WorkflowStep = { agent, pullRequest, report, 1 more... }

WorkflowStep defines a single step in a workflow action.

WorkflowTrigger = { context, manual, pullRequest, 1 more... }

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

WorkflowTriggerContext = { agent, fromTrigger, projects, 1 more... }

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