# Automations ## CancelWorkflowExecution **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. ```yaml workflowExecutionId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `workflowExecutionId: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/CancelWorkflowExecution \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## CancelWorkflowExecutionAction **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. ```yaml workflowExecutionActionId: "a1b2c3d4-5e6f-7890-abcd-ef1234567890" ``` ### Body Parameters - `workflowExecutionActionId: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/CancelWorkflowExecutionAction \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## CreateWorkflow **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 ### Body Parameters - `action: WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `description: optional string` Description must be at most 500 characters: ``` size(this) <= 500 ``` - `executor: optional Subject` Optional executor for the workflow. If not provided, defaults to the creator. Must be either the caller themselves or a service account. - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `name: optional string` Name must be between 1 and 80 characters: ``` size(this) >= 1 && size(this) <= 80 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` Automation must have between 1 and 10 triggers: ``` size(this) >= 1 && size(this) <= 10 ``` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` ### Returns - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/CreateWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{ "action": { "limits": {} } }' ``` #### Response ```json { "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, "disabled": 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" ], "integrationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "webhookId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "time": { "cronExpression": "cronExpression" } } ] }, "webhookUrl": "webhookUrl" } } ``` ## DeleteWorkflow **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. ```yaml workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" ``` ### Body Parameters - `force: optional boolean` force indicates whether to immediately delete the workflow and all related resources. When true, performs cascading deletion of: - All workflow executions - All workflow execution actions - All environments created by workflow actions - All agent executions created by workflow actions - The workflow itself When false (default), marks workflow executions for deletion and relies on background reconciliation to clean up resources. - `workflowId: optional string` ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/DeleteWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json {} ``` ## ListWorkflows **post** `/gitpod.v1.WorkflowService/ListWorkflows` ListWorkflows ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { creatorIds, hasFailedExecutionSince, search, 2 more }` - `creatorIds: optional array of string` creator_ids filters workflows by creator user IDs - `hasFailedExecutionSince: optional string` has_failed_execution_since filters workflows that have at least one failed execution with create_time >= the specified timestamp. A failed execution is one that is COMPLETED with failed_action_count > 0, or STOPPED with failed_action_count > 0 or a non-empty failure_message. This filter is mutually exclusive with status_phases. - `search: optional string` search performs case-insensitive search across workflow name, description, and ID - `statusPhases: optional array of "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` status_phases filters workflows by the phase of their latest execution. Only workflows whose most recent execution matches one of the specified phases are returned. - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `workflowIds: optional array of string` - `pagination: optional object { token, pageSize }` - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. - `sort: optional object { field, order }` sort specifies the order of results. When unspecified, results are sorted alphabetically by name ascending. - `field: optional "SORT_FIELD_UNSPECIFIED" or "SORT_FIELD_NAME" or "SORT_FIELD_RECENTLY_COMPLETED"` - `"SORT_FIELD_UNSPECIFIED"` - `"SORT_FIELD_NAME"` - `"SORT_FIELD_RECENTLY_COMPLETED"` - `order: optional SortOrder` - `"SORT_ORDER_UNSPECIFIED"` - `"SORT_ORDER_ASC"` - `"SORT_ORDER_DESC"` ### Returns - `pagination: optional object { nextToken }` - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `workflows: optional array of Workflow` - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/ListWorkflows \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "count": { "relation": "COUNT_RESPONSE_RELATION_UNSPECIFIED", "value": 0 }, "pagination": { "nextToken": "nextToken" }, "workflows": [ { "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, "disabled": 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" ], "integrationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "webhookId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "time": { "cronExpression": "cronExpression" } } ] }, "webhookUrl": "webhookUrl" } ] } ``` ## ListWorkflowExecutionActions **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. ```yaml filter: workflowExecutionIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { phases, workflowExecutionActionIds, workflowExecutionIds, workflowIds }` - `phases: optional array of "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DONE"` - `workflowExecutionActionIds: optional array of string` - `workflowExecutionIds: optional array of string` - `workflowIds: optional array of string` - `pagination: optional object { token, pageSize }` - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `pagination: optional object { nextToken }` - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `workflowExecutionActions: optional array of WorkflowExecutionAction` - `id: optional string` - `metadata: optional object { actionName, finishedAt, startedAt, 2 more }` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `actionName: optional string` Human-readable name for this action based on its context. Examples: "gitpod-io/gitpod-next" for repository context, "My Project" for project context. Will be empty string for actions created before this field was added. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowExecutionId: optional string` - `workflowId: optional string` - `spec: optional object { context, limits }` WorkflowExecutionActionSpec contains the specification for this execution action. - `context: optional AgentCodeContext` Context for the execution action - specifies where and how the action executes. This is resolved from the workflow trigger context and contains the specific project, repository, or agent context for this execution instance. - `contextUrl: optional object { environmentClassId, url }` - `environmentClassId: optional string` - `url: optional string` - `environmentId: optional string` - `projectId: optional string` - `pullRequest: optional object { id, author, draft, 6 more }` Pull request context - optional metadata about the PR being worked on This is populated when the agent execution is triggered by a PR workflow or when explicitly provided through the browser extension - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: optional object { agentExecutionId, environmentId, failures, 3 more }` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agentExecutionId: optional string` - `environmentId: optional string` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: optional "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING" or 5 more` WorkflowExecutionActionPhase defines the phases of workflow execution action. - `"WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DONE"` - `stepStatuses: optional array of object { error, finishedAt, phase, 3 more }` Step-level progress tracking - `error: optional object { code, message, meta, 2 more }` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `phase: optional "STEP_PHASE_UNSPECIFIED" or "STEP_PHASE_PENDING" or "STEP_PHASE_RUNNING" or 3 more` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `step: optional WorkflowStep` The step definition captured at execution time for immutability. This ensures the UI shows the correct step even if the workflow definition changes. - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `stepIndex: optional number` Index of the step in the workflow action steps array - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/ListWorkflowExecutionActions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "workflowExecutionActions": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "actionName": "actionName", "finishedAt": "2019-12-27T18:11:19.117Z", "startedAt": "2019-12-27T18:11:19.117Z", "workflowExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "workflowId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "context": { "contextUrl": { "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "pullRequest": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" } }, "desiredPhase": "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "limits": { "maxTime": "+9125115.360s" }, "session": "session" }, "status": { "agentExecutionId": "agentExecutionId", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "failures": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ], "phase": "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "session": "session", "stepStatuses": [ { "error": { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } }, "failureMessage": "failureMessage", "finishedAt": "2019-12-27T18:11:19.117Z", "phase": "STEP_PHASE_UNSPECIFIED", "startedAt": "2019-12-27T18:11:19.117Z", "step": { "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" } }, "stepIndex": 0 } ], "warningMessage": "warningMessage", "warnings": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ] } } ] } ``` ## ListWorkflowExecutionOutputs **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. ```yaml filter: workflowExecutionIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 50 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { workflowExecutionIds }` - `workflowExecutionIds: optional array of string` - `pagination: optional object { token, pageSize }` - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `outputs: optional array of object { actionId, values }` - `actionId: optional string` - `values: optional map[object { boolValue, floatValue, intValue, stringValue } ]` - `boolValue: optional boolean` - `floatValue: optional number` - `intValue: optional string` - `stringValue: optional string` - `pagination: optional object { nextToken }` - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/ListWorkflowExecutionOutputs \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "outputs": [ { "actionId": "actionId", "values": { "foo": { "boolValue": true, "floatValue": 0, "intValue": "intValue", "stringValue": "stringValue" } } } ], "pagination": { "nextToken": "nextToken" } } ``` ## ListWorkflowExecutions **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. ```yaml filter: workflowIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 20 ``` ### Query Parameters - `token: optional string` - `pageSize: optional number` ### Body Parameters - `filter: optional object { hasFailedActions, search, statusPhases, 2 more }` - `hasFailedActions: optional boolean` - `search: optional string` search performs case-insensitive search across workflow execution ID and trigger type - `statusPhases: optional array of "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `workflowExecutionIds: optional array of string` - `workflowIds: optional array of string` - `pagination: optional object { token, pageSize }` - `token: optional string` Token for the next set of results that was returned as next_token of a PaginationResponse - `pageSize: optional number` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. - `sort: optional Sort` sort specifies the order of results. When unspecified, results are sorted by operational priority (running first, then failed, then completed, then others). Supported sort fields: startedAt, finishedAt, createdAt. - `field: optional string` Field name to sort by, in camelCase. - `order: optional SortOrder` - `"SORT_ORDER_UNSPECIFIED"` - `"SORT_ORDER_ASC"` - `"SORT_ORDER_DESC"` ### Returns - `pagination: optional object { nextToken }` - `nextToken: optional string` Token passed for retrieving the next set of results. Empty if there are no more results - `workflowExecutions: optional array of WorkflowExecution` - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/ListWorkflowExecutions \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "workflowExecutions": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "executor": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "finishedAt": "2019-12-27T18:11:19.117Z", "startedAt": "2019-12-27T18:11:19.117Z", "workflowId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "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" } } ] }, "desiredPhase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "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" } } ] }, "session": "session", "trigger": { "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": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" }, "time": { "triggeredAt": "2019-12-27T18:11:19.117Z" } } }, "status": { "doneActionCount": 0, "failedActionCount": 0, "failureMessage": "failureMessage", "failures": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ], "pendingActionCount": 0, "phase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "runningActionCount": 0, "session": "session", "stoppedActionCount": 0, "warningMessage": "warningMessage", "warnings": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ] } } ] } ``` ## GetWorkflow **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. ```yaml workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" ``` ### Body Parameters - `workflowId: optional string` ### Returns - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/GetWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "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, "disabled": 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" ], "integrationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "webhookId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "time": { "cronExpression": "cronExpression" } } ] }, "webhookUrl": "webhookUrl" } } ``` ## GetWorkflowExecution **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. ```yaml workflowExecutionId: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Body Parameters - `workflowExecutionId: optional string` ### Returns - `workflowExecution: optional WorkflowExecution` WorkflowExecution represents a workflow execution instance. - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/GetWorkflowExecution \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "workflowExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "executor": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "finishedAt": "2019-12-27T18:11:19.117Z", "startedAt": "2019-12-27T18:11:19.117Z", "workflowId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "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" } } ] }, "desiredPhase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "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" } } ] }, "session": "session", "trigger": { "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": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" }, "time": { "triggeredAt": "2019-12-27T18:11:19.117Z" } } }, "status": { "doneActionCount": 0, "failedActionCount": 0, "failureMessage": "failureMessage", "failures": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ], "pendingActionCount": 0, "phase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "runningActionCount": 0, "session": "session", "stoppedActionCount": 0, "warningMessage": "warningMessage", "warnings": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ] } } } ``` ## GetWorkflowExecutionAction **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. ```yaml workflowExecutionActionId: "a1b2c3d4-5e6f-7890-abcd-ef1234567890" ``` ### Body Parameters - `workflowExecutionActionId: optional string` ### Returns - `workflowExecutionAction: optional WorkflowExecutionAction` WorkflowExecutionAction represents a workflow execution action instance. - `id: optional string` - `metadata: optional object { actionName, finishedAt, startedAt, 2 more }` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `actionName: optional string` Human-readable name for this action based on its context. Examples: "gitpod-io/gitpod-next" for repository context, "My Project" for project context. Will be empty string for actions created before this field was added. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowExecutionId: optional string` - `workflowId: optional string` - `spec: optional object { context, limits }` WorkflowExecutionActionSpec contains the specification for this execution action. - `context: optional AgentCodeContext` Context for the execution action - specifies where and how the action executes. This is resolved from the workflow trigger context and contains the specific project, repository, or agent context for this execution instance. - `contextUrl: optional object { environmentClassId, url }` - `environmentClassId: optional string` - `url: optional string` - `environmentId: optional string` - `projectId: optional string` - `pullRequest: optional object { id, author, draft, 6 more }` Pull request context - optional metadata about the PR being worked on This is populated when the agent execution is triggered by a PR workflow or when explicitly provided through the browser extension - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: optional object { agentExecutionId, environmentId, failures, 3 more }` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agentExecutionId: optional string` - `environmentId: optional string` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: optional "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING" or 5 more` WorkflowExecutionActionPhase defines the phases of workflow execution action. - `"WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DONE"` - `stepStatuses: optional array of object { error, finishedAt, phase, 3 more }` Step-level progress tracking - `error: optional object { code, message, meta, 2 more }` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `phase: optional "STEP_PHASE_UNSPECIFIED" or "STEP_PHASE_PENDING" or "STEP_PHASE_RUNNING" or 3 more` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `step: optional WorkflowStep` The step definition captured at execution time for immutability. This ensures the UI shows the correct step even if the workflow definition changes. - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `stepIndex: optional number` Index of the step in the workflow action steps array - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/GetWorkflowExecutionAction \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "workflowExecutionAction": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "actionName": "actionName", "finishedAt": "2019-12-27T18:11:19.117Z", "startedAt": "2019-12-27T18:11:19.117Z", "workflowExecutionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "workflowId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "context": { "contextUrl": { "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "url": "https://example.com" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "projectId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "pullRequest": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" } }, "desiredPhase": "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "limits": { "maxTime": "+9125115.360s" }, "session": "session" }, "status": { "agentExecutionId": "agentExecutionId", "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "failures": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ], "phase": "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "session": "session", "stepStatuses": [ { "error": { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } }, "failureMessage": "failureMessage", "finishedAt": "2019-12-27T18:11:19.117Z", "phase": "STEP_PHASE_UNSPECIFIED", "startedAt": "2019-12-27T18:11:19.117Z", "step": { "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" } }, "stepIndex": 0 } ], "warningMessage": "warningMessage", "warnings": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ] } } } ``` ## StartWorkflow **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. ```yaml workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" ``` ### Body Parameters - `contextOverride: optional WorkflowTriggerContext` 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. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `parameters: optional map[string]` 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. - `workflowId: optional string` ### Returns - `workflowExecution: optional WorkflowExecution` WorkflowExecution represents a workflow execution instance. - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/StartWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "workflowExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "executor": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "finishedAt": "2019-12-27T18:11:19.117Z", "startedAt": "2019-12-27T18:11:19.117Z", "workflowId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "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" } } ] }, "desiredPhase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "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" } } ] }, "session": "session", "trigger": { "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": { "id": "id", "author": "author", "draft": true, "fromBranch": "fromBranch", "repository": { "cloneUrl": "cloneUrl", "host": "host", "name": "name", "owner": "owner" }, "state": "STATE_UNSPECIFIED", "title": "title", "toBranch": "toBranch", "url": "url" }, "time": { "triggeredAt": "2019-12-27T18:11:19.117Z" } } }, "status": { "doneActionCount": 0, "failedActionCount": 0, "failureMessage": "failureMessage", "failures": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ], "pendingActionCount": 0, "phase": "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "runningActionCount": 0, "session": "session", "stoppedActionCount": 0, "warningMessage": "warningMessage", "warnings": [ { "code": "WORKFLOW_ERROR_CODE_UNSPECIFIED", "message": "message", "meta": { "foo": "string" }, "reason": "reason", "retry": { "retriable": true, "retryAfter": "+9125115.360s" } } ] } } } ``` ## UpdateWorkflow **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. ```yaml workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" name: "Updated Workflow Name" ``` - Replace all triggers: Completely replaces the workflow's trigger configuration. ```yaml 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 workflowId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047" action: limits: maxParallel: 10 maxTotal: 100 steps: - task: command: "npm test" ``` ### Body Parameters - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `description: optional string` Description must be at most 500 characters: ``` size(this) <= 500 ``` - `disabled: optional boolean` When set, enables or disables the workflow. A disabled workflow will not be triggered by any automatic trigger and manual starts are rejected. - `executor: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `name: optional string` Name must be between 1 and 80 characters: ``` size(this) >= 1 && size(this) <= 80 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` Automation can have at most 10 triggers: ``` size(this) <= 10 ``` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `workflowId: optional string` ### Returns - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```http curl https://app.gitpod.io/api/gitpod.v1.WorkflowService/UpdateWorkflow \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $GITPOD_API_KEY" \ -d '{}' ``` #### Response ```json { "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, "disabled": 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" ], "integrationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "webhookId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "time": { "cronExpression": "cronExpression" } } ] }, "webhookUrl": "webhookUrl" } } ``` ## Domain Types ### Workflow - `Workflow object { id, metadata, spec, webhookUrl }` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Workflow Action - `WorkflowAction object { limits, steps }` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` ### Workflow Execution - `WorkflowExecution object { id, metadata, spec, status }` WorkflowExecution represents a workflow execution instance. - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Workflow Execution Action - `WorkflowExecutionAction object { id, metadata, spec, status }` WorkflowExecutionAction represents a workflow execution action instance. - `id: optional string` - `metadata: optional object { actionName, finishedAt, startedAt, 2 more }` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `actionName: optional string` Human-readable name for this action based on its context. Examples: "gitpod-io/gitpod-next" for repository context, "My Project" for project context. Will be empty string for actions created before this field was added. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowExecutionId: optional string` - `workflowId: optional string` - `spec: optional object { context, limits }` WorkflowExecutionActionSpec contains the specification for this execution action. - `context: optional AgentCodeContext` Context for the execution action - specifies where and how the action executes. This is resolved from the workflow trigger context and contains the specific project, repository, or agent context for this execution instance. - `contextUrl: optional object { environmentClassId, url }` - `environmentClassId: optional string` - `url: optional string` - `environmentId: optional string` - `projectId: optional string` - `pullRequest: optional object { id, author, draft, 6 more }` Pull request context - optional metadata about the PR being worked on This is populated when the agent execution is triggered by a PR workflow or when explicitly provided through the browser extension - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: optional object { agentExecutionId, environmentId, failures, 3 more }` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agentExecutionId: optional string` - `environmentId: optional string` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: optional "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING" or 5 more` WorkflowExecutionActionPhase defines the phases of workflow execution action. - `"WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DONE"` - `stepStatuses: optional array of object { error, finishedAt, phase, 3 more }` Step-level progress tracking - `error: optional object { code, message, meta, 2 more }` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `phase: optional "STEP_PHASE_UNSPECIFIED" or "STEP_PHASE_PENDING" or "STEP_PHASE_RUNNING" or 3 more` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `step: optional WorkflowStep` The step definition captured at execution time for immutability. This ensures the UI shows the correct step even if the workflow definition changes. - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `stepIndex: optional number` Index of the step in the workflow action steps array - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Workflow Step - `WorkflowStep object { agent, pullRequest, task }` WorkflowStep defines a single step in a workflow action. - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` ### Workflow Trigger - `WorkflowTrigger object { context, manual, pullRequest, time }` 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 - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` ### Workflow Trigger Context - `WorkflowTriggerContext object { agent, fromTrigger, projects, repositories }` 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` ### Automation Cancel Execution Response - `AutomationCancelExecutionResponse = unknown` ### Automation Cancel Execution Action Response - `AutomationCancelExecutionActionResponse = unknown` ### Automation Create Response - `AutomationCreateResponse object { workflow }` - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Automation Delete Response - `AutomationDeleteResponse = unknown` ### Automation List Execution Outputs Response - `AutomationListExecutionOutputsResponse object { actionId, values }` - `actionId: optional string` - `values: optional map[object { boolValue, floatValue, intValue, stringValue } ]` - `boolValue: optional boolean` - `floatValue: optional number` - `intValue: optional string` - `stringValue: optional string` ### Automation Retrieve Response - `AutomationRetrieveResponse object { workflow }` - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Automation Retrieve Execution Response - `AutomationRetrieveExecutionResponse object { workflowExecution }` - `workflowExecution: optional WorkflowExecution` WorkflowExecution represents a workflow execution instance. - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Retrieve Execution Action Response - `AutomationRetrieveExecutionActionResponse object { workflowExecutionAction }` - `workflowExecutionAction: optional WorkflowExecutionAction` WorkflowExecutionAction represents a workflow execution action instance. - `id: optional string` - `metadata: optional object { actionName, finishedAt, startedAt, 2 more }` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `actionName: optional string` Human-readable name for this action based on its context. Examples: "gitpod-io/gitpod-next" for repository context, "My Project" for project context. Will be empty string for actions created before this field was added. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowExecutionId: optional string` - `workflowId: optional string` - `spec: optional object { context, limits }` WorkflowExecutionActionSpec contains the specification for this execution action. - `context: optional AgentCodeContext` Context for the execution action - specifies where and how the action executes. This is resolved from the workflow trigger context and contains the specific project, repository, or agent context for this execution instance. - `contextUrl: optional object { environmentClassId, url }` - `environmentClassId: optional string` - `url: optional string` - `environmentId: optional string` - `projectId: optional string` - `pullRequest: optional object { id, author, draft, 6 more }` Pull request context - optional metadata about the PR being worked on This is populated when the agent execution is triggered by a PR workflow or when explicitly provided through the browser extension - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: optional object { agentExecutionId, environmentId, failures, 3 more }` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agentExecutionId: optional string` - `environmentId: optional string` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: optional "WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING" or 5 more` WorkflowExecutionActionPhase defines the phases of workflow execution action. - `"WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_ACTION_PHASE_DONE"` - `stepStatuses: optional array of object { error, finishedAt, phase, 3 more }` Step-level progress tracking - `error: optional object { code, message, meta, 2 more }` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `phase: optional "STEP_PHASE_UNSPECIFIED" or "STEP_PHASE_PENDING" or "STEP_PHASE_RUNNING" or 3 more` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `step: optional WorkflowStep` The step definition captured at execution time for immutability. This ensures the UI shows the correct step even if the workflow definition changes. - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `stepIndex: optional number` Index of the step in the workflow action steps array - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Start Execution Response - `AutomationStartExecutionResponse object { workflowExecution }` - `workflowExecution: optional WorkflowExecution` WorkflowExecution represents a workflow execution instance. - `id: optional string` - `metadata: optional object { creator, executor, finishedAt, 2 more }` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `executor: optional Subject` - `finishedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `startedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `workflowId: optional string` - `spec: optional object { action, report, trigger }` WorkflowExecutionSpec contains the specification used for this execution. - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `trigger: optional object { context, manual, pullRequest, time }` WorkflowExecutionTrigger represents a workflow execution trigger instance. - `context: WorkflowTriggerContext` Context from the workflow trigger - copied at execution time for immutability. This allows the reconciler to create actions without fetching the workflow definition. - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - empty message since no additional data needed - `pullRequest: optional object { id, author, draft, 6 more }` PullRequest represents pull request metadata from source control systems. This message is used across workflow triggers, executions, and agent contexts to maintain consistent PR information throughout the system. - `id: optional string` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: optional string` Author name as provided by the SCM system - `draft: optional boolean` Whether this is a draft pull request - `fromBranch: optional string` Source branch name (the branch being merged from) - `repository: optional object { cloneUrl, host, name, owner }` Repository information - `cloneUrl: optional string` - `host: optional string` - `name: optional string` - `owner: optional string` - `state: optional State` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: optional string` Pull request title - `toBranch: optional string` Target branch name (the branch being merged into) - `url: optional string` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: optional object { triggeredAt }` Time trigger - just the timestamp when it was triggered - `triggeredAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `status: optional object { doneActionCount, failedActionCount, failures, 5 more }` WorkflowExecutionStatus contains the current status of a workflow execution. - `doneActionCount: optional number` - `failedActionCount: optional number` - `failures: optional array of object { code, message, meta, 2 more }` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pendingActionCount: optional number` - `phase: optional "WORKFLOW_EXECUTION_PHASE_UNSPECIFIED" or "WORKFLOW_EXECUTION_PHASE_PENDING" or "WORKFLOW_EXECUTION_PHASE_RUNNING" or 5 more` - `"WORKFLOW_EXECUTION_PHASE_UNSPECIFIED"` - `"WORKFLOW_EXECUTION_PHASE_PENDING"` - `"WORKFLOW_EXECUTION_PHASE_RUNNING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPING"` - `"WORKFLOW_EXECUTION_PHASE_STOPPED"` - `"WORKFLOW_EXECUTION_PHASE_DELETING"` - `"WORKFLOW_EXECUTION_PHASE_DELETED"` - `"WORKFLOW_EXECUTION_PHASE_COMPLETED"` - `runningActionCount: optional number` - `stoppedActionCount: optional number` - `warnings: optional array of object { code, message, meta, 2 more }` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: optional "WORKFLOW_ERROR_CODE_UNSPECIFIED" or "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR" or "WORKFLOW_ERROR_CODE_AGENT_ERROR"` Error code identifying the type of error. - `"WORKFLOW_ERROR_CODE_UNSPECIFIED"` - `"WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR"` - `"WORKFLOW_ERROR_CODE_AGENT_ERROR"` - `message: optional string` Human-readable error message. - `meta: optional map[string]` Additional metadata about the error. Common keys include: - environment_id: ID of the environment - task_id: ID of the task - service_id: ID of the service - workflow_id: ID of the workflow - workflow_execution_id: ID of the workflow execution - `reason: optional string` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: optional object { retriable, retryAfter }` Retry configuration. If not set, the error is considered non-retriable. - `retriable: optional boolean` Whether the error is retriable. - `retryAfter: optional string` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Update Response - `AutomationUpdateResponse object { workflow }` - `workflow: optional Workflow` Workflow represents a workflow configuration. - `id: optional string` - `metadata: optional object { createdAt, creator, description, 3 more }` WorkflowMetadata contains workflow metadata. - `createdAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator: optional Subject` - `id: optional string` id is the UUID of the subject - `principal: optional Principal` Principal is the principal of the subject - `"PRINCIPAL_UNSPECIFIED"` - `"PRINCIPAL_ACCOUNT"` - `"PRINCIPAL_USER"` - `"PRINCIPAL_RUNNER"` - `"PRINCIPAL_ENVIRONMENT"` - `"PRINCIPAL_SERVICE_ACCOUNT"` - `"PRINCIPAL_RUNNER_MANAGER"` - `description: optional string` - `executor: optional Subject` - `name: optional string` - `updatedAt: optional string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec: optional object { action, report, triggers }` - `action: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `limits: object { maxParallel, maxTotal, perExecution }` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `maxParallel: optional number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal: optional number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution: optional object { maxTime }` PerExecution defines limits per execution action. - `maxTime: optional string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: optional array of WorkflowStep` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: optional object { prompt }` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: optional string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest: optional object { branch, description, draft, title }` WorkflowPullRequestStep represents a pull request creation step. - `branch: optional string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: optional string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: optional boolean` - `title: optional string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: optional object { command }` WorkflowTaskStep represents a task step that executes a command. - `command: optional string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report: optional WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers: optional array of WorkflowTrigger` - `context: 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 - `agent: optional object { prompt }` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: optional string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger: optional unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: optional object { projectIds }` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds: optional array of string` - `repositories: optional object { environmentClassId, repoSelector, repositoryUrls }` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId: optional string` - `repoSelector: optional object { repoSearchString, scmHost }` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString: optional string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost: optional string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls: optional object { repoUrls }` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls: optional array of string` - `manual: optional unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest: optional object { events, integrationId, webhookId }` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: optional array of "PULL_REQUEST_EVENT_UNSPECIFIED" or "PULL_REQUEST_EVENT_OPENED" or "PULL_REQUEST_EVENT_UPDATED" or 4 more` - `"PULL_REQUEST_EVENT_UNSPECIFIED"` - `"PULL_REQUEST_EVENT_OPENED"` - `"PULL_REQUEST_EVENT_UPDATED"` - `"PULL_REQUEST_EVENT_APPROVED"` - `"PULL_REQUEST_EVENT_MERGED"` - `"PULL_REQUEST_EVENT_CLOSED"` - `"PULL_REQUEST_EVENT_READY_FOR_REVIEW"` - `integrationId: optional string` 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. - `webhookId: optional string` 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. - `time: optional object { cronExpression }` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression: optional string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl: optional string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks