Gitpod API Reference | Projects

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
```

query Parameters

token: string

Optional

pageSize: number

Optional

(maximum: 100, minimum: 0, default: 25)

Response fields

pagination: { nextToken }

Optional

pagination contains the pagination options for listing organizations

projects: Array<

Project

Optional

Request example

curl https://app.gitpod.io/api/gitpod.v1.ProjectService/ListProjects \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200Example

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "projects": [
    {
      "environmentClass": {
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "localRunner": true
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "automationsFilePath": "automationsFilePath",
      "devcontainerFilePath": "devcontainerFilePath",
      "initializer": {
        "specs": [
          {
            "contextUrl": {
              "url": "https://example.com"
            },
            "git": {
              "checkoutLocation": "checkoutLocation",
              "cloneTarget": "cloneTarget",
              "remoteUri": "remoteUri",
              "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED",
              "upstreamRemoteUri": "upstreamRemoteUri"
            }
          }
        ]
      },
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "id",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "name": "x",
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "updatedAt": "2019-12-27T18:11:19.117Z"
      },
      "usedBy": {
        "subjects": [
          {
            "id": "id",
            "principal": "PRINCIPAL_UNSPECIFIED"
          }
        ],
        "totalSubjects": 0
      }
    }
  ]
}

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...