LogoGitpod API Reference

Projects

projects

Methods

Create Project -> { project }
post/gitpod.v1.ProjectService/CreateProject

Creates a new project with specified configuration.

Use this method to:

  • Set up development projects
  • Configure project environments
  • Define project settings
  • Initialize project content

Examples

  • Create basic project:

    Creates a project with minimal configuration.

    name: "Web Application"
environmentClass:
  environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"

  • Create project with devcontainer:

    Creates a project with custom development container.

    name: "Backend Service"
environmentClass:
  environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"
Create Project From Environment -> { project }
post/gitpod.v1.ProjectService/CreateProjectFromEnvironment

Creates a new project using an existing environment as a template.

Use this method to:

  • Clone environment configurations
  • Create projects from templates
  • Share environment setups

Examples

  • Create from environment:

    Creates a project based on existing environment.

    name: "Frontend Project"
environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"
Delete Project -> unknown
post/gitpod.v1.ProjectService/DeleteProject

Deletes a project permanently.

Use this method to:

  • Remove unused projects
  • Clean up test projects
  • Delete obsolete configurations

Examples

  • Delete project:

    Permanently removes a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
List Projects -> ProjectsPage<
Project
>
post/gitpod.v1.ProjectService/ListProjects

Lists projects with optional filtering.

Use this method to:

  • View all accessible projects
  • Browse project configurations
  • Monitor project status

Examples

  • List projects:

    Shows all projects with pagination.

    pagination:
  pageSize: 20
Get Project -> { project }
post/gitpod.v1.ProjectService/GetProject

Gets details about a specific project.

Use this method to:

  • View project configuration
  • Check project status
  • Get project metadata

Examples

  • Get project details:

    Retrieves information about a specific project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
Update Project -> { project }
post/gitpod.v1.ProjectService/UpdateProject

Updates a project's configuration.

Use this method to:

  • Modify project settings
  • Update environment class
  • Change project name
  • Configure initializers

Examples

  • Update project name:

    Changes the project's display name.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "New Project Name"

  • Update environment class:

    Changes the project's environment class.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
environmentClass:
  environmentClassId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"

Domain types

EnvironmentInitializer = { specs }

EnvironmentInitializer specifies how an environment is to be initialized

Project = { environmentClass, id, automationsFilePath, 4 more... }
ProjectEnvironmentClass = { environmentClassId, localRunner }
ProjectMetadata = { createdAt, creator, name, 2 more... }
Projects

Policies

projects.policies

Methods

Create Project Policy -> { policy }
post/gitpod.v1.ProjectService/CreateProjectPolicy

Creates a new policy for a project.

Use this method to:

  • Set up access controls
  • Define group permissions
  • Configure role-based access

Examples

  • Create admin policy:

    Grants admin access to a group.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_ADMIN
Delete Project Policy -> unknown
post/gitpod.v1.ProjectService/DeleteProjectPolicy

Deletes a project policy.

Use this method to:

  • Remove access controls
  • Revoke permissions
  • Clean up policies

Examples

  • Delete policy:

    Removes a group's access policy.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
List Project Policies -> PoliciesPage<
ProjectPolicy
>
post/gitpod.v1.ProjectService/ListProjectPolicies

Lists policies for a project.

Use this method to:

  • View access controls
  • Check policy configurations
  • Audit permissions

Examples

  • List policies:

    Shows all policies for a project.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20
Update Project Policy -> { policy }
post/gitpod.v1.ProjectService/UpdateProjectPolicy

Updates an existing project policy.

Use this method to:

  • Modify access levels
  • Change group roles
  • Update permissions

Examples

  • Update policy role:

    Changes a group's access level.

    projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_EDITOR

Domain types

ProjectPolicy = { groupId, role }
ProjectRole = "PROJECT_ROLE_UNSPECIFIED" | "PROJECT_ROLE_ADMIN" | "PROJECT_ROLE_USER" | 1 more...