# Automations ## CancelWorkflowExecution `automations.cancel_execution(AutomationCancelExecutionParams**kwargs) -> object` **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" ``` ### Parameters - `workflow_execution_id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.automations.cancel_execution( workflow_execution_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response) ``` #### Response ```json {} ``` ## CancelWorkflowExecutionAction `automations.cancel_execution_action(AutomationCancelExecutionActionParams**kwargs) -> object` **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" ``` ### Parameters - `workflow_execution_action_id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.automations.cancel_execution_action( workflow_execution_action_id="a1b2c3d4-5e6f-7890-abcd-ef1234567890", ) print(response) ``` #### Response ```json {} ``` ## CreateWorkflow `automations.create(AutomationCreateParams**kwargs) -> AutomationCreateResponse` **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 ### Parameters - `action: WorkflowActionParam` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `description: Optional[str]` 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[str]` 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[str]` Name must be between 1 and 80 characters: ``` size(this) >= 1 && size(this) <= 80 ``` - `report: Optional[WorkflowActionParam]` WorkflowAction defines the actions to be executed in a workflow. - `triggers: Optional[Iterable[WorkflowTriggerParam]]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` ### Returns - `class AutomationCreateResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) automation = client.automations.create( action={ "limits": {} }, ) print(automation.workflow) ``` #### 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 `automations.delete(AutomationDeleteParams**kwargs) -> object` **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" ``` ### Parameters - `force: Optional[bool]` 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. - `workflow_id: Optional[str]` ### Returns - `object` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) automation = client.automations.delete( workflow_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", ) print(automation) ``` #### Response ```json {} ``` ## ListWorkflows `automations.list(AutomationListParams**kwargs) -> SyncWorkflowsPage[Workflow]` **post** `/gitpod.v1.WorkflowService/ListWorkflows` ListWorkflows ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `creator_ids: Optional[Sequence[str]]` creator_ids filters workflows by creator user IDs - `has_failed_execution_since: Optional[Union[str, datetime]]` 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[str]` search performs case-insensitive search across workflow name, description, and ID - `status_phases: Optional[List[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `workflow_ids: Optional[Sequence[str]]` - `pagination: Optional[Pagination]` - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` 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 alphabetically by name ascending. - `field: Optional[Literal["SORT_FIELD_UNSPECIFIED", "SORT_FIELD_NAME", "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 - `class Workflow: …` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.automations.list() page = page.workflows[0] print(page.id) ``` #### 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 `automations.list_execution_actions(AutomationListExecutionActionsParams**kwargs) -> SyncWorkflowExecutionActionsPage[WorkflowExecutionAction]` **post** `/gitpod.v1.WorkflowService/ListWorkflowExecutionActions` Lists workflow execution actions with optional filtering. Use this method to: - Monitor individual action execution status - Debug action failures - Track resource usage per action ### Examples - List execution actions for workflow execution: Shows all execution actions for a specific workflow execution. ```yaml filter: workflowExecutionIds: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `phases: Optional[List[Literal["WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING", "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING", 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"` - `workflow_execution_action_ids: Optional[Sequence[str]]` - `workflow_execution_ids: Optional[Sequence[str]]` - `workflow_ids: Optional[Sequence[str]]` - `pagination: Optional[Pagination]` - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class WorkflowExecutionAction: …` WorkflowExecutionAction represents a workflow execution action instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `action_name: Optional[str]` 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. - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_execution_id: Optional[str]` - `workflow_id: Optional[str]` - `spec: Optional[Spec]` 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. - `context_url: Optional[ContextURL]` - `environment_class_id: Optional[str]` - `url: Optional[str]` - `environment_id: Optional[str]` - `project_id: Optional[str]` - `pull_request: Optional[PullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: Optional[SpecLimits]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: Optional[Status]` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agent_execution_id: Optional[str]` - `environment_id: Optional[str]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: Optional[Literal["WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING", "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING", 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"` - `step_statuses: Optional[List[StatusStepStatus]]` Step-level progress tracking - `error: Optional[StatusStepStatusError]` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusStepStatusErrorRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finished_at: Optional[datetime]` 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[Literal["STEP_PHASE_UNSPECIFIED", "STEP_PHASE_PENDING", "STEP_PHASE_RUNNING", 3 more]]` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `started_at: Optional[datetime]` 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[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `step_index: Optional[int]` Index of the step in the workflow action steps array - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.automations.list_execution_actions( filter={ "workflow_execution_ids": ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] }, pagination={ "page_size": 20 }, ) page = page.workflow_execution_actions[0] print(page.id) ``` #### 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 `automations.list_execution_outputs(AutomationListExecutionOutputsParams**kwargs) -> SyncOutputsPage[AutomationListExecutionOutputsResponse]` **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 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `workflow_execution_ids: Optional[Sequence[str]]` - `pagination: Optional[Pagination]` - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. ### Returns - `class AutomationListExecutionOutputsResponse: …` - `action_id: Optional[str]` - `values: Optional[Dict[str, Values]]` - `bool_value: Optional[bool]` - `float_value: Optional[float]` - `int_value: Optional[str]` - `string_value: Optional[str]` ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.automations.list_execution_outputs( filter={ "workflow_execution_ids": ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] }, pagination={ "page_size": 50 }, ) page = page.outputs[0] print(page.action_id) ``` #### Response ```json { "outputs": [ { "actionId": "actionId", "values": { "foo": { "boolValue": true, "floatValue": 0, "intValue": "intValue", "stringValue": "stringValue" } } } ], "pagination": { "nextToken": "nextToken" } } ``` ## ListWorkflowExecutions `automations.list_executions(AutomationListExecutionsParams**kwargs) -> SyncWorkflowExecutionsPage[WorkflowExecution]` **post** `/gitpod.v1.WorkflowService/ListWorkflowExecutions` Lists workflow executions with optional filtering. Use this method to: - Monitor workflow execution history - Track execution status - Debug workflow issues ### Examples - List executions for workflow: Shows all executions for a specific workflow. ```yaml filter: workflowIds: ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` - `has_failed_actions: Optional[bool]` - `search: Optional[str]` search performs case-insensitive search across workflow execution ID and trigger type - `status_phases: Optional[List[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `workflow_execution_ids: Optional[Sequence[str]]` - `workflow_ids: Optional[Sequence[str]]` - `pagination: Optional[Pagination]` - `token: Optional[str]` Token for the next set of results that was returned as next_token of a PaginationResponse - `page_size: Optional[int]` 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[str]` Field name to sort by, in camelCase. - `order: Optional[SortOrder]` - `"SORT_ORDER_UNSPECIFIED"` - `"SORT_ORDER_ASC"` - `"SORT_ORDER_DESC"` ### Returns - `class WorkflowExecution: …` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) page = client.automations.list_executions( filter={ "workflow_ids": ["b0e12f6c-4c67-429d-a4a6-d9838b5da047"] }, pagination={ "page_size": 20 }, ) page = page.workflow_executions[0] print(page.id) ``` #### 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 `automations.retrieve(AutomationRetrieveParams**kwargs) -> AutomationRetrieveResponse` **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" ``` ### Parameters - `workflow_id: Optional[str]` ### Returns - `class AutomationRetrieveResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) automation = client.automations.retrieve( workflow_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", ) print(automation.workflow) ``` #### 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 `automations.retrieve_execution(AutomationRetrieveExecutionParams**kwargs) -> AutomationRetrieveExecutionResponse` **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" ``` ### Parameters - `workflow_execution_id: Optional[str]` ### Returns - `class AutomationRetrieveExecutionResponse: …` - `workflow_execution: Optional[WorkflowExecution]` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.automations.retrieve_execution( workflow_execution_id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.workflow_execution) ``` #### 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 `automations.retrieve_execution_action(AutomationRetrieveExecutionActionParams**kwargs) -> AutomationRetrieveExecutionActionResponse` **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" ``` ### Parameters - `workflow_execution_action_id: Optional[str]` ### Returns - `class AutomationRetrieveExecutionActionResponse: …` - `workflow_execution_action: Optional[WorkflowExecutionAction]` WorkflowExecutionAction represents a workflow execution action instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `action_name: Optional[str]` 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. - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_execution_id: Optional[str]` - `workflow_id: Optional[str]` - `spec: Optional[Spec]` 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. - `context_url: Optional[ContextURL]` - `environment_class_id: Optional[str]` - `url: Optional[str]` - `environment_id: Optional[str]` - `project_id: Optional[str]` - `pull_request: Optional[PullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: Optional[SpecLimits]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: Optional[Status]` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agent_execution_id: Optional[str]` - `environment_id: Optional[str]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: Optional[Literal["WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING", "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING", 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"` - `step_statuses: Optional[List[StatusStepStatus]]` Step-level progress tracking - `error: Optional[StatusStepStatusError]` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusStepStatusErrorRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finished_at: Optional[datetime]` 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[Literal["STEP_PHASE_UNSPECIFIED", "STEP_PHASE_PENDING", "STEP_PHASE_RUNNING", 3 more]]` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `started_at: Optional[datetime]` 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[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `step_index: Optional[int]` Index of the step in the workflow action steps array - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.automations.retrieve_execution_action( workflow_execution_action_id="a1b2c3d4-5e6f-7890-abcd-ef1234567890", ) print(response.workflow_execution_action) ``` #### 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 `automations.start_execution(AutomationStartExecutionParams**kwargs) -> AutomationStartExecutionResponse` **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" ``` ### Parameters - `context_override: Optional[WorkflowTriggerContextParam]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `parameters: Optional[Dict[str, str]]` 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. - `workflow_id: Optional[str]` ### Returns - `class AutomationStartExecutionResponse: …` - `workflow_execution: Optional[WorkflowExecution]` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) response = client.automations.start_execution( workflow_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", ) print(response.workflow_execution) ``` #### 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 `automations.update(AutomationUpdateParams**kwargs) -> AutomationUpdateResponse` **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" ``` ### Parameters - `action: Optional[WorkflowActionParam]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `description: Optional[str]` Description must be at most 500 characters: ``` size(this) <= 500 ``` - `disabled: Optional[bool]` 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[str]` 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[str]` Name must be between 1 and 80 characters: ``` size(this) >= 1 && size(this) <= 80 ``` - `report: Optional[WorkflowActionParam]` WorkflowAction defines the actions to be executed in a workflow. - `triggers: Optional[Iterable[WorkflowTriggerParam]]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `workflow_id: Optional[str]` ### Returns - `class AutomationUpdateResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```python import os from gitpod import Gitpod client = Gitpod( bearer_token=os.environ.get("GITPOD_API_KEY"), # This is the default and can be omitted ) automation = client.automations.update( triggers=[{ "context": { "projects": { "project_ids": ["new-project-id"] } }, "manual": {}, }], workflow_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047", ) print(automation.workflow) ``` #### 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 - `class Workflow: …` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Workflow Action - `class WorkflowAction: …` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` ### Workflow Execution - `class WorkflowExecution: …` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Workflow Execution Action - `class WorkflowExecutionAction: …` WorkflowExecutionAction represents a workflow execution action instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `action_name: Optional[str]` 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. - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_execution_id: Optional[str]` - `workflow_id: Optional[str]` - `spec: Optional[Spec]` 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. - `context_url: Optional[ContextURL]` - `environment_class_id: Optional[str]` - `url: Optional[str]` - `environment_id: Optional[str]` - `project_id: Optional[str]` - `pull_request: Optional[PullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: Optional[SpecLimits]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: Optional[Status]` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agent_execution_id: Optional[str]` - `environment_id: Optional[str]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: Optional[Literal["WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING", "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING", 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"` - `step_statuses: Optional[List[StatusStepStatus]]` Step-level progress tracking - `error: Optional[StatusStepStatusError]` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusStepStatusErrorRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finished_at: Optional[datetime]` 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[Literal["STEP_PHASE_UNSPECIFIED", "STEP_PHASE_PENDING", "STEP_PHASE_RUNNING", 3 more]]` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `started_at: Optional[datetime]` 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[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `step_index: Optional[int]` Index of the step in the workflow action steps array - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Workflow Step - `class WorkflowStep: …` WorkflowStep defines a single step in a workflow action. - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` ### Workflow Trigger - `class WorkflowTrigger: …` WorkflowTrigger defines when a workflow should be executed. Each trigger type defines a specific condition that will cause the workflow to execute: - Manual: Triggered explicitly by user action via StartWorkflow RPC - Time: Triggered automatically based on cron schedule - PullRequest: Triggered automatically when specified PR events occur Trigger Semantics: - Each trigger instance can create multiple workflow executions - Multiple triggers of the same workflow can fire simultaneously - Each trigger execution is independent and tracked separately - Triggers are evaluated in the context specified by WorkflowTriggerContext - `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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` ### Workflow Trigger Context - `class 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` ### Automation Create Response - `class AutomationCreateResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Automation List Execution Outputs Response - `class AutomationListExecutionOutputsResponse: …` - `action_id: Optional[str]` - `values: Optional[Dict[str, Values]]` - `bool_value: Optional[bool]` - `float_value: Optional[float]` - `int_value: Optional[str]` - `string_value: Optional[str]` ### Automation Retrieve Response - `class AutomationRetrieveResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Automation Retrieve Execution Response - `class AutomationRetrieveExecutionResponse: …` - `workflow_execution: Optional[WorkflowExecution]` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Retrieve Execution Action Response - `class AutomationRetrieveExecutionActionResponse: …` - `workflow_execution_action: Optional[WorkflowExecutionAction]` WorkflowExecutionAction represents a workflow execution action instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionActionMetadata contains workflow execution action metadata. - `action_name: Optional[str]` 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. - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_execution_id: Optional[str]` - `workflow_id: Optional[str]` - `spec: Optional[Spec]` 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. - `context_url: Optional[ContextURL]` - `environment_class_id: Optional[str]` - `url: Optional[str]` - `environment_id: Optional[str]` - `project_id: Optional[str]` - `pull_request: Optional[PullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[PullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `limits: Optional[SpecLimits]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `status: Optional[Status]` WorkflowExecutionActionStatus contains the current status of a workflow execution action. - `agent_execution_id: Optional[str]` - `environment_id: Optional[str]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution action to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `phase: Optional[Literal["WORKFLOW_EXECUTION_ACTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_ACTION_PHASE_PENDING", "WORKFLOW_EXECUTION_ACTION_PHASE_RUNNING", 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"` - `step_statuses: Optional[List[StatusStepStatus]]` Step-level progress tracking - `error: Optional[StatusStepStatusError]` Structured error that caused the step to fail. Provides detailed error code, message, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusStepStatusErrorRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `finished_at: Optional[datetime]` 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[Literal["STEP_PHASE_UNSPECIFIED", "STEP_PHASE_PENDING", "STEP_PHASE_RUNNING", 3 more]]` - `"STEP_PHASE_UNSPECIFIED"` - `"STEP_PHASE_PENDING"` - `"STEP_PHASE_RUNNING"` - `"STEP_PHASE_DONE"` - `"STEP_PHASE_FAILED"` - `"STEP_PHASE_CANCELLED"` - `started_at: Optional[datetime]` 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[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `step_index: Optional[int]` Index of the step in the workflow action steps array - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution action. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Start Execution Response - `class AutomationStartExecutionResponse: …` - `workflow_execution: Optional[WorkflowExecution]` WorkflowExecution represents a workflow execution instance. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowExecutionMetadata contains workflow execution metadata. - `creator: Optional[Subject]` - `id: Optional[str]` 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]` - `finished_at: Optional[datetime]` 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. - `started_at: Optional[datetime]` 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. - `workflow_id: Optional[str]` - `spec: Optional[Spec]` WorkflowExecutionSpec contains the specification used for this execution. - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[SpecTrigger]` 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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - empty message since no additional data needed - `pull_request: Optional[SpecTriggerPullRequest]` 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[str]` Unique identifier from the source system (e.g., "123" for GitHub PR #123) - `author: Optional[str]` Author name as provided by the SCM system - `draft: Optional[bool]` Whether this is a draft pull request - `from_branch: Optional[str]` Source branch name (the branch being merged from) - `repository: Optional[SpecTriggerPullRequestRepository]` Repository information - `clone_url: Optional[str]` - `host: Optional[str]` - `name: Optional[str]` - `owner: Optional[str]` - `state: Optional[State]` Current state of the pull request - `"STATE_UNSPECIFIED"` - `"STATE_OPEN"` - `"STATE_CLOSED"` - `"STATE_MERGED"` - `title: Optional[str]` Pull request title - `to_branch: Optional[str]` Target branch name (the branch being merged into) - `url: Optional[str]` Pull request URL (e.g., "https://github.com/owner/repo/pull/123") - `time: Optional[SpecTriggerTime]` Time trigger - just the timestamp when it was triggered - `triggered_at: Optional[datetime]` 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[Status]` WorkflowExecutionStatus contains the current status of a workflow execution. - `done_action_count: Optional[int]` - `failed_action_count: Optional[int]` - `failures: Optional[List[StatusFailure]]` Structured failures that caused the workflow execution to fail. Provides detailed error codes, messages, and retry information. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusFailureRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. - `pending_action_count: Optional[int]` - `phase: Optional[Literal["WORKFLOW_EXECUTION_PHASE_UNSPECIFIED", "WORKFLOW_EXECUTION_PHASE_PENDING", "WORKFLOW_EXECUTION_PHASE_RUNNING", 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"` - `running_action_count: Optional[int]` - `stopped_action_count: Optional[int]` - `warnings: Optional[List[StatusWarning]]` Structured warnings about the workflow execution. Provides detailed warning codes and messages. - `code: Optional[Literal["WORKFLOW_ERROR_CODE_UNSPECIFIED", "WORKFLOW_ERROR_CODE_ENVIRONMENT_ERROR", "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[str]` Human-readable error message. - `meta: Optional[Dict[str, str]]` 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[str]` Reason explaining why the error occurred. Examples: "not_found", "stopped", "deleted", "creation_failed", "start_failed" - `retry: Optional[StatusWarningRetry]` Retry configuration. If not set, the error is considered non-retriable. - `retriable: Optional[bool]` Whether the error is retriable. - `retry_after: Optional[str]` Suggested duration to wait before retrying. Only meaningful when retriable is true. ### Automation Update Response - `class AutomationUpdateResponse: …` - `workflow: Optional[Workflow]` Workflow represents a workflow configuration. - `id: Optional[str]` - `metadata: Optional[Metadata]` WorkflowMetadata contains workflow metadata. - `created_at: Optional[datetime]` 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[str]` 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[str]` - `executor: Optional[Subject]` - `name: Optional[str]` - `updated_at: Optional[datetime]` 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[Spec]` - `action: Optional[WorkflowAction]` WorkflowAction defines the actions to be executed in a workflow. - `limits: Limits` Limits defines execution limits for workflow actions. Concurrent actions limit cannot exceed total actions limit: ``` this.max_parallel <= this.max_total ``` - `max_parallel: Optional[int]` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `max_total: Optional[int]` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `per_execution: Optional[LimitsPerExecution]` PerExecution defines limits per execution action. - `max_time: Optional[str]` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps: Optional[List[WorkflowStep]]` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent: Optional[Agent]` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt: Optional[str]` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pull_request: Optional[PullRequest]` WorkflowPullRequestStep represents a pull request creation step. - `branch: Optional[str]` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description: Optional[str]` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft: Optional[bool]` - `title: Optional[str]` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task: Optional[Task]` WorkflowTaskStep represents a task step that executes a command. - `command: Optional[str]` 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[List[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[Agent]` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt: Optional[str]` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `from_trigger: Optional[object]` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects: Optional[Projects]` Execute workflow in specific project environments. Creates environments for each specified project. - `project_ids: Optional[List[str]]` - `repositories: Optional[Repositories]` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environment_class_id: Optional[str]` - `repo_selector: Optional[RepositoriesRepoSelector]` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repo_search_string: Optional[str]` 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. - `scm_host: Optional[str]` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repository_urls: Optional[RepositoriesRepositoryURLs]` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repo_urls: Optional[List[str]]` - `manual: Optional[object]` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pull_request: Optional[PullRequest]` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events: Optional[List[Literal["PULL_REQUEST_EVENT_UNSPECIFIED", "PULL_REQUEST_EVENT_OPENED", "PULL_REQUEST_EVENT_UPDATED", 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"` - `integration_id: Optional[str]` 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. - `webhook_id: Optional[str]` 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[Time]` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cron_expression: Optional[str]` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhook_url: Optional[str]` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks