Creates a development environment from a context URL (e.g. Git repository) and starts it.

The class field must be a valid environment class ID. You can find a list of available environment classes with the ListEnvironmentClasses method.

Examples

• Create from context URL:

  Creates an environment from a Git repository URL with default settings.

  spec:
    machine:
      class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    content:
      initializer:
        specs:
          - contextUrl:
              url: "https://github.com/gitpod-io/gitpod"
  

• Create from Git repository:

  Creates an environment from a Git repository with specific branch targeting.

  spec:
    machine:
      class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    content:
      initializer:
        specs:
          - git:
              remoteUri: "https://github.com/gitpod-io/gitpod"
              cloneTarget: "main"
              targetMode: "CLONE_TARGET_MODE_REMOTE_BRANCH"
  

• Create with custom timeout and ports:

  Creates an environment with custom inactivity timeout and exposed port configuration.

  spec:
    machine:
      class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    content:
      initializer:
        specs:
          - contextUrl:
              url: "https://github.com/gitpod-io/gitpod"
    timeout:
      disconnected: "7200s"  # 2 hours in seconds
    ports:
      - port: 3000
        admission: "ADMISSION_LEVEL_EVERYONE"
        name: "Web App"
  

Creates an environment from an existing project configuration and starts it.

This method uses project settings as defaults but allows overriding specific configurations. Project settings take precedence over default configurations, while custom specifications in the request override project settings.

Examples

• Create with project defaults:

  Creates an environment using all default settings from the project configuration.

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

• Create with custom compute resources:

  Creates an environment from project with custom machine class and timeout settings.

  projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  spec:
    machine:
      class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
    timeout:
      disconnected: "14400s"  # 4 hours in seconds
  

Creates an access token for retrieving environment logs.

Generated tokens are valid for one hour and provide read-only access to the environment's logs.

Examples

• Generate logs token:

  Creates a temporary access token for retrieving environment logs.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  

Permanently deletes an environment.

Running environments are automatically stopped before deletion. If force is true, the environment is deleted immediately without graceful shutdown.

Examples

• Delete with graceful shutdown:

  Deletes an environment after gracefully stopping it.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  force: false
  

• Force delete:

  Immediately deletes an environment without waiting for graceful shutdown.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  force: true
  

Records environment activity to prevent automatic shutdown.

Activity signals should be sent every 5 minutes while the environment is actively being used. The source must be between 3-80 characters.

Examples

• Signal VS Code activity:

  Records VS Code editor activity to prevent environment shutdown.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  activitySignal:
    source: "VS Code"
    timestamp: "2025-02-12T14:30:00Z"
  

Gets details about a specific environment including its status, configuration, and context URL.

Use this method to:

• Check if an environment is ready to use
• Get connection details for IDE and exposed ports
• Monitor environment health and resource usage
• Debug environment setup issues

Examples

• Get environment details:

  Retrieves detailed information about a specific environment using its unique identifier.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  

Starts a stopped environment.

Use this method to resume work on a previously stopped environment. The environment retains its configuration and workspace content from when it was stopped.

Examples

• Start an environment:

  Resumes a previously stopped environment with its existing configuration.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  

Stops a running environment.

Use this method to pause work while preserving the environment's state. The environment can be resumed later using StartEnvironment.

Examples

• Stop an environment:

  Gracefully stops a running environment while preserving its state.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  

Updates an environment's configuration while it is running.

Updates are limited to:

• Git credentials (username, email)
• SSH public keys
• Content initialization
• Port configurations
• Automation files
• Environment timeouts

Examples

• Update Git credentials:

  Updates the Git configuration for the environment.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    content:
      gitUsername: "example-user"
      gitEmail: "[email protected]"
  

• Add SSH public key:

  Adds a new SSH public key for authentication.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    sshPublicKeys:
      - id: "0194b7c1-c954-718d-91a4-9a742aa5fc11"
        value: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
  

• Update content session:

  Updates the content session identifier for the environment.

  environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
  spec:
    content:
      session: "0194b7c1-c954-718d-91a4-9a742aa5fc11"
  

Note: Machine class changes require stopping the environment and creating a new one.

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.

  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
  

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.

  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.

  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"
  

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.

  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  force: false
  

• Force delete:

  Immediately removes a service.

  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  force: true
  

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.

  filter:
    environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
  pagination:
    pageSize: 20
  

• Filter by reference:

  Lists services matching specific references.

  filter:
    references: ["web-server", "database"]
  pagination:
    pageSize: 20
  

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.

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

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.

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

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.

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

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.

  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.

  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  metadata:
    triggeredBy:
      trigger:
        - postDevcontainerStart: true
        - manual: true
  

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.

  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.

  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"]
  

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.

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

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.

  filter:
    environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
  pagination:
    pageSize: 20
  

• Filter by reference:

  Lists tasks matching specific references.

  filter:
    references: ["build", "test"]
  pagination:
    pageSize: 20
  

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.

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

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.

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

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.

  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  spec:
    command: "npm run test:coverage"
  

• Update triggers:

  Modifies when the task runs.

  id: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  metadata:
    triggeredBy:
      trigger:
        - postEnvironmentStart: true
  

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.

  filter:
    environmentIds: ["07e03a28-65a5-4d98-b532-8ea67b188048"]
  pagination:
    pageSize: 20
  

• Filter by phase:

  Lists executions in specific phases.

  filter:
    phases: ["TASK_EXECUTION_PHASE_RUNNING", "TASK_EXECUTION_PHASE_FAILED"]
  pagination:
    pageSize: 20
  

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.

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

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.

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

Lists available environment classes with their specifications and resource limits.

Use this method to understand what types of environments you can create and their capabilities. Environment classes define the compute resources and features available to your environments.

Examples

• List all available classes:

  Retrieves a list of all environment classes with their specifications.

  {}
  

buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE