## UpdateWorkflow `client.automations.update(AutomationUpdateParamsbody, RequestOptionsoptions?): 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 - `body: AutomationUpdateParams` - `action?: WorkflowAction | null` 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 ``` - `maxParallel?: number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal?: number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution?: PerExecution` PerExecution defines limits per execution action. - `maxTime?: string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps?: Array` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent?: Agent` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt?: string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest?: PullRequest` WorkflowPullRequestStep represents a pull request creation step. - `branch?: string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description?: string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft?: boolean` - `title?: string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task?: Task` WorkflowTaskStep represents a task step that executes a command. - `command?: string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `description?: string | null` Description must be at most 500 characters: ``` size(this) <= 500 ``` - `disabled?: boolean | null` When set, enables or disables the workflow. A disabled workflow will not be triggered by any automatic trigger and manual starts are rejected. - `executor?: Subject | null` - `id?: string` id is the UUID of the subject - `principal?: 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?: string | null` Name must be between 1 and 80 characters: ``` size(this) >= 1 && size(this) <= 80 ``` - `report?: WorkflowAction | null` WorkflowAction defines the actions to be executed in a workflow. - `triggers?: Array` 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?: Agent` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt?: string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger?: unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects?: Projects` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds?: Array` - `repositories?: Repositories` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId?: string` - `repoSelector?: RepoSelector` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString?: string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost?: string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls?: RepositoryURLs` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls?: Array` - `manual?: unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest?: PullRequest` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events?: Array<"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"` - `integrationId?: string | null` integration_id is the optional ID of an integration that acts as the source of webhook events. When set, the trigger will be activated when the webhook receives events. - `webhookId?: string | null` 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?: Time` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression?: string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `workflowId?: string` ### Returns - `AutomationUpdateResponse` - `workflow?: Workflow` Workflow represents a workflow configuration. - `id?: string` - `metadata?: Metadata` WorkflowMetadata contains workflow metadata. - `createdAt?: string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `creator?: Subject` - `id?: string` id is the UUID of the subject - `principal?: 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?: string` - `executor?: Subject` - `name?: string` - `updatedAt?: string` A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`](http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime\(\)) to obtain a formatter capable of generating timestamps in this format. - `spec?: Spec` - `action?: 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 ``` - `maxParallel?: number` Maximum parallel actions must be between 1 and 25: ``` this >= 1 && this <= 25 ``` - `maxTotal?: number` Maximum total actions must be between 1 and 100: ``` this >= 1 && this <= 100 ``` - `perExecution?: PerExecution` PerExecution defines limits per execution action. - `maxTime?: string` Maximum time allowed for a single execution action. Use standard duration format (e.g., "30m" for 30 minutes, "2h" for 2 hours). - `steps?: Array` Automation must have between 1 and 50 steps: ``` size(this) >= 1 && size(this) <= 50 ``` - `agent?: Agent` WorkflowAgentStep represents an agent step that executes with a prompt. - `prompt?: string` Prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `pullRequest?: PullRequest` WorkflowPullRequestStep represents a pull request creation step. - `branch?: string` Branch name must be between 1 and 255 characters: ``` size(this) >= 1 && size(this) <= 255 ``` - `description?: string` Description must be at most 20,000 characters: ``` size(this) <= 20000 ``` - `draft?: boolean` - `title?: string` Title must be between 1 and 500 characters: ``` size(this) >= 1 && size(this) <= 500 ``` - `task?: Task` WorkflowTaskStep represents a task step that executes a command. - `command?: string` Command must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `report?: WorkflowAction` WorkflowAction defines the actions to be executed in a workflow. - `triggers?: Array` - `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?: Agent` Execute workflow in agent-managed environments. Agent receives the specified prompt and manages execution context. - `prompt?: string` Agent prompt must be between 1 and 20,000 characters: ``` size(this) >= 1 && size(this) <= 20000 ``` - `fromTrigger?: unknown` Use context derived from the trigger event. Currently only supported for PullRequest triggers - uses PR repository context. - `projects?: Projects` Execute workflow in specific project environments. Creates environments for each specified project. - `projectIds?: Array` - `repositories?: Repositories` Execute workflow in environments created from repository URLs. Supports both explicit repository URLs and search patterns. - `environmentClassId?: string` - `repoSelector?: RepoSelector` RepositorySelector defines how to select repositories for workflow execution. Combines a search string with an SCM host to identify repositories. - `repoSearchString?: string` Search string to match repositories using SCM-specific search patterns. For GitHub: supports GitHub search syntax (e.g., "org:gitpod-io language:go", "user:octocat stars:>100") For GitLab: supports GitLab search syntax See SCM provider documentation for supported search patterns. - `scmHost?: string` SCM host where the search should be performed (e.g., "github.com", "gitlab.com") - `repositoryUrls?: RepositoryURLs` RepositoryURLs contains a list of explicit repository URLs. Creates one action per repository URL. - `repoUrls?: Array` - `manual?: unknown` Manual trigger - executed when StartWorkflow RPC is called. No additional configuration needed. - `pullRequest?: PullRequest` Pull request trigger - executed when specified PR events occur. Only triggers for PRs in repositories matching the trigger context. - `events?: Array<"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"` - `integrationId?: string | null` integration_id is the optional ID of an integration that acts as the source of webhook events. When set, the trigger will be activated when the webhook receives events. - `webhookId?: string | null` 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?: Time` Time-based trigger - executed automatically based on cron schedule. Uses standard cron expression format (minute hour day month weekday). - `cronExpression?: string` Cron expression must be between 1 and 100 characters: ``` size(this) >= 1 && size(this) <= 100 ``` - `webhookUrl?: string` Webhook URL for triggering this workflow via HTTP POST Format: {base_url}/workflows/{workflow_id}/webhooks ### Example ```typescript import Gitpod from '@gitpod/sdk'; const client = new Gitpod({ bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted }); const automation = await client.automations.update({ triggers: [ { context: { projects: { projectIds: ['new-project-id'] } }, manual: {}, }, ], workflowId: 'b0e12f6c-4c67-429d-a4a6-d9838b5da047', }); console.log(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" } } ```