# Automations ## UpsertAutomationsFile `environments.automations.upsert(AutomationUpsertParams**kwargs) -> AutomationUpsertResponse` **post** `/gitpod.v1.EnvironmentAutomationService/UpsertAutomationsFile` Upserts the automations file for the given environment. Use this method to: - Configure environment automations - Update automation settings - Manage automation files ### Examples - Update automations file: Updates or creates the automations configuration. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" automationsFile: services: web-server: name: "Web Server" description: "Development web server" commands: start: "npm run dev" ready: "curl -s http://localhost:3000" triggeredBy: - postDevcontainerStart tasks: build: name: "Build Project" description: "Builds the project artifacts" command: "npm run build" triggeredBy: - postEnvironmentStart ``` ### Parameters - `automations_file: Optional[AutomationsFileParam]` WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields. This includes marking a field as "reserved" in the proto file, this will also break reading the yaml. - `services: Optional[Dict[str, Services]]` - `commands: Optional[ServicesCommands]` - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `description: Optional[str]` - `name: Optional[str]` - `role: Optional[Literal["", "default", "editor", "ai-agent"]]` - `""` - `"default"` - `"editor"` - `"ai-agent"` - `runs_on: Optional[RunsOn]` - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `tasks: Optional[Dict[str, Tasks]]` - `command: Optional[str]` - `depends_on: Optional[List[str]]` - `description: Optional[str]` - `name: Optional[str]` - `runs_on: Optional[RunsOn]` - `triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `environment_id: Optional[str]` ### Returns - `class AutomationUpsertResponse: …` - `updated_service_ids: Optional[List[str]]` - `updated_task_ids: Optional[List[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 ) response = client.environments.automations.upsert( automations_file={ "services": { "web-server": { "commands": { "ready": "curl -s http://localhost:3000", "start": "npm run dev", }, "description": "Development web server", "name": "Web Server", "triggered_by": ["postDevcontainerStart"], } }, "tasks": { "build": { "command": "npm run build", "description": "Builds the project artifacts", "name": "Build Project", "triggered_by": ["postEnvironmentStart"], } }, }, environment_id="07e03a28-65a5-4d98-b532-8ea67b188048", ) print(response.updated_service_ids) ``` #### Response ```json { "updatedServiceIds": [ "string" ], "updatedTaskIds": [ "string" ] } ``` ## Domain Types ### Automations File - `class AutomationsFile: …` WARN: Do not remove any field here, as it will break reading automation yaml files. We error if there are any unknown fields in the yaml (to ensure the yaml is correct), but would break if we removed any fields. This includes marking a field as "reserved" in the proto file, this will also break reading the yaml. - `services: Optional[Dict[str, Services]]` - `commands: Optional[ServicesCommands]` - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `description: Optional[str]` - `name: Optional[str]` - `role: Optional[Literal["", "default", "editor", "ai-agent"]]` - `""` - `"default"` - `"editor"` - `"ai-agent"` - `runs_on: Optional[RunsOn]` - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` - `tasks: Optional[Dict[str, Tasks]]` - `command: Optional[str]` - `depends_on: Optional[List[str]]` - `description: Optional[str]` - `name: Optional[str]` - `runs_on: Optional[RunsOn]` - `triggered_by: Optional[List[Literal["manual", "postEnvironmentStart", "postDevcontainerStart", "prebuild"]]]` - `"manual"` - `"postEnvironmentStart"` - `"postDevcontainerStart"` - `"prebuild"` ### Automation Upsert Response - `class AutomationUpsertResponse: …` - `updated_service_ids: Optional[List[str]]` - `updated_task_ids: Optional[List[str]]` # Services ## CreateService `environments.automations.services.create(ServiceCreateParams**kwargs) -> ServiceCreateResponse` **post** `/gitpod.v1.EnvironmentAutomationService/CreateService` Creates a new automation service for an environment. Use this method to: - Set up long-running services - Configure service triggers - Define service dependencies - Specify runtime environments ### Examples - Create basic service: Creates a simple service with start command. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "web-server" name: "Web Server" description: "Runs the development web server" triggeredBy: - postDevcontainerStart: true spec: commands: start: "npm run dev" ready: "curl -s http://localhost:3000" ``` - Create Docker-based service: Creates a service running in a specific container. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "redis" name: "Redis Server" description: "Redis cache service" spec: commands: start: "redis-server" runsOn: docker: image: "redis:7" ``` ### Parameters - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadataParam]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpecParam]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. ### Returns - `class ServiceCreateResponse: …` - `service: Service` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### 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 ) service = client.environments.automations.services.create( environment_id="07e03a28-65a5-4d98-b532-8ea67b188048", metadata={ "description": "Runs the development web server", "name": "Web Server", "reference": "web-server", "triggered_by": [{ "post_devcontainer_start": True }], }, spec={ "commands": { "ready": "curl -s http://localhost:3000", "start": "npm run dev", } }, ) print(service.service) ``` #### Response ```json { "service": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "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", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } } ``` ## DeleteService `environments.automations.services.delete(ServiceDeleteParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/DeleteService` Deletes an automation service. This call does not block until the service is deleted. If the service is not stopped it will be stopped before deletion. Use this method to: - Remove unused services - Clean up service configurations - Stop and delete services ### Examples - Delete service: Removes a service after stopping it. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" force: false ``` - Force delete: Immediately removes a service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" force: true ``` ### Parameters - `id: Optional[str]` - `force: Optional[bool]` ### 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 ) service = client.environments.automations.services.delete( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", force=False, ) print(service) ``` #### Response ```json {} ``` ## ListServices `environments.automations.services.list(ServiceListParams**kwargs) -> SyncServicesPage[Service]` **post** `/gitpod.v1.EnvironmentAutomationService/ListServices` Lists automation services with optional filtering. Use this method to: - View all services in an environment - Filter services by reference - Monitor service status ### Examples - List environment services: Shows all services for an environment. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by reference: Lists services matching specific references. ```yaml filter: references: ["web-server", "database"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` filter contains the filter options for listing services - `environment_ids: Optional[Sequence[str]]` environment_ids filters the response to only services of these environments - `references: Optional[Sequence[str]]` references filters the response to only services with these references - `roles: Optional[List[ServiceRole]]` roles filters the response to only services with these roles - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `service_ids: Optional[Sequence[str]]` service_ids filters the response to only services with these IDs - `pagination: Optional[Pagination]` pagination contains the pagination options for listing services - `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 Service: …` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### 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.environments.automations.services.list( filter={ "references": ["web-server", "database"] }, pagination={ "page_size": 20 }, ) page = page.services[0] print(page.id) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "services": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "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", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } ] } ``` ## GetService `environments.automations.services.retrieve(ServiceRetrieveParams**kwargs) -> ServiceRetrieveResponse` **post** `/gitpod.v1.EnvironmentAutomationService/GetService` Gets details about a specific automation service. Use this method to: - Check service status - View service configuration - Monitor service health - Retrieve service metadata ### Examples - Get service details: Retrieves information about a specific service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class ServiceRetrieveResponse: …` - `service: Service` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### 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 ) service = client.environments.automations.services.retrieve( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(service.service) ``` #### Response ```json { "service": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "environmentId": "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", "name": "x", "reference": "reference", "role": "SERVICE_ROLE_UNSPECIFIED", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "commands": { "ready": "ready", "start": "x", "stop": "stop" }, "desiredPhase": "SERVICE_PHASE_UNSPECIFIED", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} }, "session": "session", "specVersion": "specVersion" }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "output": { "foo": "string" }, "phase": "SERVICE_PHASE_UNSPECIFIED", "session": "session", "statusVersion": "statusVersion" } } } ``` ## StartService `environments.automations.services.start(ServiceStartParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/StartService` Starts an automation service. This call does not block until the service is started. This call will not error if the service is already running or has been started. Use this method to: - Start stopped services - Resume service operations - Trigger service initialization ### Examples - Start service: Starts a previously stopped service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `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.environments.automations.services.start( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response) ``` #### Response ```json {} ``` ## StopService `environments.automations.services.stop(ServiceStopParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/StopService` Stops an automation service. This call does not block until the service is stopped. This call will not error if the service is already stopped or has been stopped. Use this method to: - Pause service operations - Gracefully stop services - Prepare for updates ### Examples - Stop service: Gracefully stops a running service. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `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.environments.automations.services.stop( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response) ``` #### Response ```json {} ``` ## UpdateService `environments.automations.services.update(ServiceUpdateParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/UpdateService` Updates an automation service configuration. Use this method to: - Modify service commands - Update triggers - Change runtime settings - Adjust dependencies ### Examples - Update commands: Changes service start and ready commands. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" spec: commands: start: "npm run start:dev" ready: "curl -s http://localhost:8080" ``` - Update triggers: Modifies when the service starts. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" metadata: triggeredBy: trigger: - postDevcontainerStart: true - manual: true ``` ### Parameters - `id: Optional[str]` - `metadata: Optional[Metadata]` - `description: Optional[str]` - `name: Optional[str]` - `role: Optional[ServiceRole]` - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[MetadataTriggeredBy]` - `trigger: Optional[Iterable[AutomationTrigger]]` - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[Spec]` Changing the spec of a service is a complex operation. The spec of a service can only be updated if the service is in a stopped state. If the service is running, it must be stopped first. - `commands: Optional[SpecCommands]` - `ready: Optional[str]` - `start: Optional[str]` - `stop: Optional[str]` - `env: Optional[Iterable[EnvironmentVariableItem]]` - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[Status]` Service status updates are only expected from the executing environment. As a client of this API you are not expected to provide this field. Updating this field requires the `environmentservice:update_status` permission. - `failure_message: Optional[str]` - `log_url: Optional[str]` - `output: Optional[Dict[str, str]]` setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `session: 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 ) service = client.environments.automations.services.update( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", spec={ "commands": { "ready": "curl -s http://localhost:8080", "start": "npm run start:dev", } }, ) print(service) ``` #### Response ```json {} ``` ## Domain Types ### Service - `class Service: …` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### Service Metadata - `class ServiceMetadata: …` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` ### Service Phase - `Literal["SERVICE_PHASE_UNSPECIFIED", "SERVICE_PHASE_STARTING", "SERVICE_PHASE_RUNNING", 4 more]` - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` ### Service Role - `Literal["SERVICE_ROLE_UNSPECIFIED", "SERVICE_ROLE_DEFAULT", "SERVICE_ROLE_EDITOR", 2 more]` - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` ### Service Spec - `class ServiceSpec: …` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. ### Service Status - `class ServiceStatus: …` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### Service Create Response - `class ServiceCreateResponse: …` - `service: Service` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. ### Service Retrieve Response - `class ServiceRetrieveResponse: …` - `service: Service` - `id: str` - `environment_id: Optional[str]` - `metadata: Optional[ServiceMetadata]` - `created_at: Optional[datetime]` created_at is the time the service was created. - `creator: Optional[Subject]` creator describes the principal who created the service. - `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]` description is a user-facing description for the service. It can be used to provide context and documentation for the service. - `name: Optional[str]` name is a user-facing name for the service. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the service. - `reference: Optional[str]` reference is a user-facing identifier for the service which must be unique on the environment. It is used to express dependencies between services, and to identify the service in user interactions (e.g. the CLI). - `role: Optional[ServiceRole]` role specifies the intended role or purpose of the service. - `"SERVICE_ROLE_UNSPECIFIED"` - `"SERVICE_ROLE_DEFAULT"` - `"SERVICE_ROLE_EDITOR"` - `"SERVICE_ROLE_AI_AGENT"` - `"SERVICE_ROLE_SECURITY_AGENT"` - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the service. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[ServiceSpec]` - `commands: Optional[Commands]` commands contains the commands to start, stop and check the readiness of the service - `ready: Optional[str]` ready is an optional command that is run repeatedly until it exits with a zero exit code. If set, the service will first go into a Starting phase, and then into a Running phase once the ready command exits with a zero exit code. - `start: Optional[str]` start is the command to start and run the service. If start exits, the service will transition to the following phase: - Stopped: if the exit code is 0 - Failed: if the exit code is not 0 If the stop command is not set, the start command will receive a SIGTERM signal when the service is requested to stop. If it does not exit within 2 minutes, it will receive a SIGKILL signal. - `stop: Optional[str]` stop is an optional command that runs when the service is requested to stop. If set, instead of sending a SIGTERM signal to the start command, the stop command will be run. Once the stop command exits, the start command will receive a SIGKILL signal. If the stop command exits with a non-zero exit code, the service will transition to the Failed phase. If the stop command does not exit within 2 minutes, a SIGKILL signal will be sent to both the start and stop commands. - `desired_phase: Optional[ServicePhase]` desired_phase is the phase the service should be in. Used to start or stop the service. - `"SERVICE_PHASE_UNSPECIFIED"` - `"SERVICE_PHASE_STARTING"` - `"SERVICE_PHASE_RUNNING"` - `"SERVICE_PHASE_STOPPING"` - `"SERVICE_PHASE_STOPPED"` - `"SERVICE_PHASE_FAILED"` - `"SERVICE_PHASE_DELETED"` - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the service. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the service should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `session: Optional[str]` session should be changed to trigger a restart of the service. If a service exits it will not be restarted until the session is changed. - `spec_version: Optional[str]` version of the spec. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. - `status: Optional[ServiceStatus]` - `failure_message: Optional[str]` failure_message summarises why the service failed to operate. If this is non-empty the service has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url contains the URL at which the service logs can be accessed. - `output: Optional[Dict[str, str]]` output contains the output of the service. setting an output field to empty string will unset it. - `phase: Optional[ServicePhase]` phase is the current phase of the service. - `session: Optional[str]` session is the current session of the service. - `status_version: Optional[str]` version of the status update. Service instances themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. # Tasks ## CreateTask `environments.automations.tasks.create(TaskCreateParams**kwargs) -> TaskCreateResponse` **post** `/gitpod.v1.EnvironmentAutomationService/CreateTask` Creates a new automation task. Use this method to: - Define one-off or scheduled tasks - Set up build or test automation - Configure task dependencies - Specify execution environments ### Examples - Create basic task: Creates a simple build task. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "build" name: "Build Project" description: "Builds the project artifacts" triggeredBy: - postEnvironmentStart: true spec: command: "npm run build" ``` - Create task with dependencies: Creates a task that depends on other services. ```yaml environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048" metadata: reference: "test" name: "Run Tests" description: "Runs the test suite" spec: command: "npm test" dependsOn: ["d2c94c27-3b76-4a42-b88c-95a85e392c68"] ``` ### Parameters - `depends_on: Optional[Sequence[str]]` - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### Returns - `class TaskCreateResponse: …` - `task: Task` - `id: str` - `depends_on: Optional[List[str]]` dependencies specifies the IDs of the automations this task depends on. - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### 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 ) task = client.environments.automations.tasks.create( environment_id="07e03a28-65a5-4d98-b532-8ea67b188048", metadata={ "description": "Builds the project artifacts", "name": "Build Project", "reference": "build", "triggered_by": [{ "post_environment_start": True }], }, spec={ "command": "npm run build" }, ) print(task.task) ``` #### Response ```json { "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "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", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ``` ## DeleteTask `environments.automations.tasks.delete(TaskDeleteParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/DeleteTask` Deletes an automation task. Use this method to: - Remove unused tasks - Clean up task configurations - Delete obsolete automations ### Examples - Delete task: Removes a task and its configuration. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `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 ) task = client.environments.automations.tasks.delete( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(task) ``` #### Response ```json {} ``` ## ListTasks `environments.automations.tasks.list(TaskListParams**kwargs) -> SyncTasksPage[Task]` **post** `/gitpod.v1.EnvironmentAutomationService/ListTasks` Lists automation tasks with optional filtering. Use this method to: - View all tasks in an environment - Filter tasks by reference - Monitor task status ### Examples - List environment tasks: Shows all tasks for an environment. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by reference: Lists tasks matching specific references. ```yaml filter: references: ["build", "test"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` filter contains the filter options for listing tasks - `environment_ids: Optional[Sequence[str]]` environment_ids filters the response to only tasks of these environments - `references: Optional[Sequence[str]]` references filters the response to only services with these references - `task_ids: Optional[Sequence[str]]` task_ids filters the response to only tasks with these IDs - `pagination: Optional[Pagination]` pagination contains the pagination options for listing tasks - `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 Task: …` - `id: str` - `depends_on: Optional[List[str]]` dependencies specifies the IDs of the automations this task depends on. - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### 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.environments.automations.tasks.list( filter={ "references": ["build", "test"] }, pagination={ "page_size": 20 }, ) page = page.tasks[0] print(page.id) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "tasks": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "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", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } ] } ``` ## GetTask `environments.automations.tasks.retrieve(TaskRetrieveParams**kwargs) -> TaskRetrieveResponse` **post** `/gitpod.v1.EnvironmentAutomationService/GetTask` Gets details about a specific automation task. Use this method to: - Check task configuration - View task dependencies - Monitor task status ### Examples - Get task details: Retrieves information about a specific task. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class TaskRetrieveResponse: …` - `task: Task` - `id: str` - `depends_on: Optional[List[str]]` dependencies specifies the IDs of the automations this task depends on. - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### 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 ) task = client.environments.automations.tasks.retrieve( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(task.task) ``` #### Response ```json { "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" ], "environmentId": "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", "name": "x", "reference": "reference", "triggeredBy": [ { "beforeSnapshot": true, "manual": true, "postDevcontainerStart": true, "postEnvironmentStart": true, "postMachineStart": true, "prebuild": true } ] }, "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ``` ## StartTask `environments.automations.tasks.start(TaskStartParams**kwargs) -> TaskStartResponse` **post** `/gitpod.v1.EnvironmentAutomationService/StartTask` Starts a task by creating a new task execution. This call does not block until the task is started; the task will be started asynchronously. Use this method to: - Trigger task execution - Run one-off tasks - Start scheduled tasks immediately ### Examples - Start task: Creates a new execution of a task. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class TaskStartResponse: …` - `task_execution: TaskExecution` - `id: str` - `metadata: Optional[TaskExecutionMetadata]` - `completed_at: Optional[datetime]` completed_at is the time the task execution was done. - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created/started the task run. - `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"` - `environment_id: Optional[str]` environment_id is the ID of the environment in which the task run is executed. - `started_at: Optional[datetime]` started_at is the time the task execution actually started to run. - `started_by: Optional[str]` started_by describes the trigger that started the task execution. - `task_id: Optional[str]` task_id is the ID of the main task being executed. - `spec: Optional[TaskExecutionSpec]` - `desired_phase: Optional[TaskExecutionPhase]` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: Optional[List[Plan]]` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: Optional[List[PlanStep]]` - `id: Optional[str]` ID is the ID of the execution step - `depends_on: Optional[List[str]]` - `label: Optional[str]` - `service_id: Optional[str]` - `task: Optional[PlanStepTask]` - `id: Optional[str]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[TaskExecutionStatus]` - `failure_message: Optional[str]` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: Optional[TaskExecutionPhase]` the phase of a task execution represents the aggregated phase of all steps. - `status_version: Optional[str]` version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `steps: Optional[List[Step]]` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: Optional[str]` ID is the ID of the execution step - `failure_message: Optional[str]` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: Optional[Dict[str, str]]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: Optional[TaskExecutionPhase]` phase is the current phase of the execution step ### 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.environments.automations.tasks.start( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response.task_execution) ``` #### Response ```json { "taskExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } } ``` ## UpdateTask `environments.automations.tasks.update(TaskUpdateParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/UpdateTask` Updates an automation task configuration. Use this method to: - Modify task commands - Update task triggers - Change dependencies - Adjust execution settings ### Examples - Update command: Changes the task's command. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" spec: command: "npm run test:coverage" ``` - Update triggers: Modifies when the task runs. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" metadata: triggeredBy: trigger: - postEnvironmentStart: true ``` ### Parameters - `id: Optional[str]` - `depends_on: Optional[Sequence[str]]` dependencies specifies the IDs of the automations this task depends on. - `metadata: Optional[Metadata]` - `description: Optional[str]` - `name: Optional[str]` - `triggered_by: Optional[MetadataTriggeredBy]` - `trigger: Optional[Iterable[AutomationTrigger]]` - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[Spec]` - `command: Optional[str]` - `env: Optional[Iterable[EnvironmentVariableItem]]` - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### 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 ) task = client.environments.automations.tasks.update( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", spec={ "command": "npm run test:coverage" }, ) print(task) ``` #### Response ```json {} ``` ## Domain Types ### Task Create Response - `class TaskCreateResponse: …` - `task: Task` - `id: str` - `depends_on: Optional[List[str]]` dependencies specifies the IDs of the automations this task depends on. - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### Task Retrieve Response - `class TaskRetrieveResponse: …` - `task: Task` - `id: str` - `depends_on: Optional[List[str]]` dependencies specifies the IDs of the automations this task depends on. - `environment_id: Optional[str]` - `metadata: Optional[TaskMetadata]` - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created the task. - `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]` description is a user-facing description for the task. It can be used to provide context and documentation for the task. - `name: Optional[str]` name is a user-facing name for the task. Unlike the reference, this field is not unique, and not referenced by the system. This is a short descriptive name for the task. - `reference: Optional[str]` reference is a user-facing identifier for the task which must be unique on the environment. It is used to express dependencies between tasks, and to identify the task in user interactions (e.g. the CLI). - `triggered_by: Optional[List[AutomationTrigger]]` triggered_by is a list of trigger that start the task. - `before_snapshot: Optional[bool]` - `manual: Optional[bool]` - `post_devcontainer_start: Optional[bool]` - `post_environment_start: Optional[bool]` - `post_machine_start: Optional[bool]` - `prebuild: Optional[bool]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. ### Task Start Response - `class TaskStartResponse: …` - `task_execution: TaskExecution` - `id: str` - `metadata: Optional[TaskExecutionMetadata]` - `completed_at: Optional[datetime]` completed_at is the time the task execution was done. - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created/started the task run. - `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"` - `environment_id: Optional[str]` environment_id is the ID of the environment in which the task run is executed. - `started_at: Optional[datetime]` started_at is the time the task execution actually started to run. - `started_by: Optional[str]` started_by describes the trigger that started the task execution. - `task_id: Optional[str]` task_id is the ID of the main task being executed. - `spec: Optional[TaskExecutionSpec]` - `desired_phase: Optional[TaskExecutionPhase]` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: Optional[List[Plan]]` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: Optional[List[PlanStep]]` - `id: Optional[str]` ID is the ID of the execution step - `depends_on: Optional[List[str]]` - `label: Optional[str]` - `service_id: Optional[str]` - `task: Optional[PlanStepTask]` - `id: Optional[str]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[TaskExecutionStatus]` - `failure_message: Optional[str]` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: Optional[TaskExecutionPhase]` the phase of a task execution represents the aggregated phase of all steps. - `status_version: Optional[str]` version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `steps: Optional[List[Step]]` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: Optional[str]` ID is the ID of the execution step - `failure_message: Optional[str]` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: Optional[Dict[str, str]]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: Optional[TaskExecutionPhase]` phase is the current phase of the execution step # Executions ## ListTaskExecutions `environments.automations.tasks.executions.list(ExecutionListParams**kwargs) -> SyncTaskExecutionsPage[TaskExecution]` **post** `/gitpod.v1.EnvironmentAutomationService/ListTaskExecutions` Lists executions of automation tasks. Use this method to: - View task execution history - Monitor running tasks - Track task completion status ### Examples - List all executions: Shows execution history for all tasks. ```yaml filter: environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"] pagination: pageSize: 20 ``` - Filter by phase: Lists executions in specific phases. ```yaml filter: phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"] pagination: pageSize: 20 ``` ### Parameters - `token: Optional[str]` - `page_size: Optional[int]` - `filter: Optional[Filter]` filter contains the filter options for listing task runs - `environment_ids: Optional[Sequence[str]]` environment_ids filters the response to only task runs of these environments - `phases: Optional[List[TaskExecutionPhase]]` phases filters the response to only task runs in these phases - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `task_ids: Optional[Sequence[str]]` task_ids filters the response to only task runs of these tasks - `task_references: Optional[Sequence[str]]` task_references filters the response to only task runs with this reference - `pagination: Optional[Pagination]` pagination contains the pagination options for listing task runs - `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 TaskExecution: …` - `id: str` - `metadata: Optional[TaskExecutionMetadata]` - `completed_at: Optional[datetime]` completed_at is the time the task execution was done. - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created/started the task run. - `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"` - `environment_id: Optional[str]` environment_id is the ID of the environment in which the task run is executed. - `started_at: Optional[datetime]` started_at is the time the task execution actually started to run. - `started_by: Optional[str]` started_by describes the trigger that started the task execution. - `task_id: Optional[str]` task_id is the ID of the main task being executed. - `spec: Optional[TaskExecutionSpec]` - `desired_phase: Optional[TaskExecutionPhase]` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: Optional[List[Plan]]` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: Optional[List[PlanStep]]` - `id: Optional[str]` ID is the ID of the execution step - `depends_on: Optional[List[str]]` - `label: Optional[str]` - `service_id: Optional[str]` - `task: Optional[PlanStepTask]` - `id: Optional[str]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[TaskExecutionStatus]` - `failure_message: Optional[str]` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: Optional[TaskExecutionPhase]` the phase of a task execution represents the aggregated phase of all steps. - `status_version: Optional[str]` version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `steps: Optional[List[Step]]` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: Optional[str]` ID is the ID of the execution step - `failure_message: Optional[str]` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: Optional[Dict[str, str]]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: Optional[TaskExecutionPhase]` phase is the current phase of the execution step ### 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.environments.automations.tasks.executions.list( filter={ "phases": ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"] }, pagination={ "page_size": 20 }, ) page = page.task_executions[0] print(page.id) ``` #### Response ```json { "pagination": { "nextToken": "nextToken" }, "taskExecutions": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } ] } ``` ## GetTaskExecution `environments.automations.tasks.executions.retrieve(ExecutionRetrieveParams**kwargs) -> ExecutionRetrieveResponse` **post** `/gitpod.v1.EnvironmentAutomationService/GetTaskExecution` Gets details about a specific task execution. Use this method to: - Monitor execution progress - View execution logs - Check execution status - Debug failed executions ### Examples - Get execution details: Retrieves information about a specific task execution. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `id: Optional[str]` ### Returns - `class ExecutionRetrieveResponse: …` - `task_execution: TaskExecution` - `id: str` - `metadata: Optional[TaskExecutionMetadata]` - `completed_at: Optional[datetime]` completed_at is the time the task execution was done. - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created/started the task run. - `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"` - `environment_id: Optional[str]` environment_id is the ID of the environment in which the task run is executed. - `started_at: Optional[datetime]` started_at is the time the task execution actually started to run. - `started_by: Optional[str]` started_by describes the trigger that started the task execution. - `task_id: Optional[str]` task_id is the ID of the main task being executed. - `spec: Optional[TaskExecutionSpec]` - `desired_phase: Optional[TaskExecutionPhase]` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: Optional[List[Plan]]` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: Optional[List[PlanStep]]` - `id: Optional[str]` ID is the ID of the execution step - `depends_on: Optional[List[str]]` - `label: Optional[str]` - `service_id: Optional[str]` - `task: Optional[PlanStepTask]` - `id: Optional[str]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[TaskExecutionStatus]` - `failure_message: Optional[str]` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: Optional[TaskExecutionPhase]` the phase of a task execution represents the aggregated phase of all steps. - `status_version: Optional[str]` version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `steps: Optional[List[Step]]` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: Optional[str]` ID is the ID of the execution step - `failure_message: Optional[str]` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: Optional[Dict[str, str]]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: Optional[TaskExecutionPhase]` phase is the current phase of the execution step ### 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 ) execution = client.environments.automations.tasks.executions.retrieve( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(execution.task_execution) ``` #### Response ```json { "taskExecution": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "metadata": { "completedAt": "2019-12-27T18:11:19.117Z", "createdAt": "2019-12-27T18:11:19.117Z", "creator": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "principal": "PRINCIPAL_UNSPECIFIED" }, "environmentId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "startedAt": "2019-12-27T18:11:19.117Z", "startedBy": "startedBy", "taskId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }, "spec": { "desiredPhase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "plan": [ { "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "dependsOn": [ "string" ], "label": "label", "serviceId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "task": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "spec": { "command": "command", "env": [ { "name": "x", "value": "value", "valueFrom": { "secretRef": { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" } } } ], "runsOn": { "docker": { "environment": [ "string" ], "image": "x" }, "machine": {} } } } } ] } ] }, "status": { "failureMessage": "failureMessage", "logUrl": "logUrl", "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED", "statusVersion": "statusVersion", "steps": [ { "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "failureMessage": "failureMessage", "output": { "foo": "string" }, "phase": "TASK_EXECUTION_PHASE_UNSPECIFIED" } ] } } } ``` ## StopTaskExecution `environments.automations.tasks.executions.stop(ExecutionStopParams**kwargs) -> object` **post** `/gitpod.v1.EnvironmentAutomationService/StopTaskExecution` Stops a running task execution. Use this method to: - Cancel long-running tasks - Stop failed executions - Interrupt task processing ### Examples - Stop execution: Stops a running task execution. ```yaml id: "d2c94c27-3b76-4a42-b88c-95a85e392c68" ``` ### Parameters - `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.environments.automations.tasks.executions.stop( id="d2c94c27-3b76-4a42-b88c-95a85e392c68", ) print(response) ``` #### Response ```json {} ``` ## Domain Types ### Execution Retrieve Response - `class ExecutionRetrieveResponse: …` - `task_execution: TaskExecution` - `id: str` - `metadata: Optional[TaskExecutionMetadata]` - `completed_at: Optional[datetime]` completed_at is the time the task execution was done. - `created_at: Optional[datetime]` created_at is the time the task was created. - `creator: Optional[Subject]` creator describes the principal who created/started the task run. - `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"` - `environment_id: Optional[str]` environment_id is the ID of the environment in which the task run is executed. - `started_at: Optional[datetime]` started_at is the time the task execution actually started to run. - `started_by: Optional[str]` started_by describes the trigger that started the task execution. - `task_id: Optional[str]` task_id is the ID of the main task being executed. - `spec: Optional[TaskExecutionSpec]` - `desired_phase: Optional[TaskExecutionPhase]` desired_phase is the phase the task execution should be in. Used to stop a running task execution early. - `"TASK_EXECUTION_PHASE_UNSPECIFIED"` - `"TASK_EXECUTION_PHASE_PENDING"` - `"TASK_EXECUTION_PHASE_RUNNING"` - `"TASK_EXECUTION_PHASE_SUCCEEDED"` - `"TASK_EXECUTION_PHASE_FAILED"` - `"TASK_EXECUTION_PHASE_STOPPED"` - `plan: Optional[List[Plan]]` plan is a list of groups of steps. The steps in a group are executed concurrently, while the groups are executed sequentially. The order of the groups is the order in which they are executed. - `steps: Optional[List[PlanStep]]` - `id: Optional[str]` ID is the ID of the execution step - `depends_on: Optional[List[str]]` - `label: Optional[str]` - `service_id: Optional[str]` - `task: Optional[PlanStepTask]` - `id: Optional[str]` - `spec: Optional[TaskSpec]` - `command: Optional[str]` command contains the command the task should execute - `env: Optional[List[EnvironmentVariableItem]]` env specifies environment variables for the task. - `name: Optional[str]` name is the environment variable name. - `value: Optional[str]` value is a literal string value. - `value_from: Optional[EnvironmentVariableSource]` value_from specifies a source for the value. - `secret_ref: SecretRef` secret_ref references a secret by ID. - `id: Optional[str]` id is the UUID of the secret to reference. - `runs_on: Optional[RunsOn]` runs_on specifies the environment the task should run on. - `docker: Optional[Docker]` - `environment: Optional[List[str]]` - `image: Optional[str]` - `machine: Optional[object]` Machine runs the service/task directly on the VM/machine level. - `status: Optional[TaskExecutionStatus]` - `failure_message: Optional[str]` failure_message summarises why the task execution failed to operate. If this is non-empty the task execution has failed to operate and will likely transition to a failed state. - `log_url: Optional[str]` log_url is the URL to the logs of the task's steps. If this is empty, the task either has no logs or has not yet started. - `phase: Optional[TaskExecutionPhase]` the phase of a task execution represents the aggregated phase of all steps. - `status_version: Optional[str]` version of the status update. Task executions themselves are unversioned, but their status has different versions. The value of this field has no semantic meaning (e.g. don't interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. - `steps: Optional[List[Step]]` steps provides the status for each individual step of the task execution. If a step is missing it has not yet started. - `id: Optional[str]` ID is the ID of the execution step - `failure_message: Optional[str]` failure_message summarises why the step failed to operate. If this is non-empty the step has failed to operate and will likely transition to a failed state. - `output: Optional[Dict[str, str]]` output contains the output of the task execution. setting an output field to empty string will unset it. - `phase: Optional[TaskExecutionPhase]` phase is the current phase of the execution step