--- title: "CreateProject" method: POST path: "/gitpod.v1.ProjectService/CreateProject" tags: ["gitpod.v1.ProjectService"] --- # CreateProject `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. ```yaml name: "Web Application" initializer: specs: - git: remoteUri: "https://github.com/org/repo" ``` - Create project with devcontainer: Creates a project with custom development container. ```yaml name: "Backend Service" initializer: specs: - git: remoteUri: "https://github.com/org/backend" devcontainerFilePath: ".devcontainer/devcontainer.json" automationsFilePath: ".gitpod/automations.yaml" ``` ## Request body - GitpodV1CreateProjectRequest - `automationsFilePath` string — automations_file_path is the path to the automations file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `devcontainerFilePath` string — devcontainer_file_path is the path to the devcontainer file relative to the repo root path must not be absolute (start with a /): ``` this.matches('^$|^[^/].*') ``` - `initializer` GitpodV1EnvironmentInitializer, required — unresolved $ref - `name` string - `prebuildConfiguration` GitpodV1ProjectPrebuildConfiguration — ProjectPrebuildConfiguration defines how prebuilds are created for a project. Prebuilds create environment snapshots that enable faster environment startup times. - `enableJetbrainsWarmup` boolean — enable_jetbrains_warmup controls whether JetBrains IDE warmup runs during prebuilds. - `enabled` boolean — enabled controls whether prebuilds are created for this project. When disabled, no automatic prebuilds will be triggered. - `environmentClassIds` string[] — environment_class_ids specifies which environment classes should have prebuilds created. If empty, no prebuilds are created. - `executor` GitpodV1Subject - `id` string, uuid — id is the UUID of the subject - `principal` 'PRINCIPAL_UNSPECIFIED' | 'PRINCIPAL_ACCOUNT' | 'PRINCIPAL_USER' | 'PRINCIPAL_RUNNER' | 'PRINCIPAL_ENVIRONMENT' | 'PRINCIPAL_SERVICE_ACCOUNT' | 'PRINCIPAL_RUNNER_MANAGER' | 'PRINCIPAL_AGENT_EXECUTION' - `timeout` string, regex — A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like "day" or "month". It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years. # Examples Example 1: Compute Duration from two Timestamps in pseudo code. Timestamp start = ...; Timestamp end = ...; Duration duration = ...; duration.seconds = end.seconds - start.seconds; duration.nanos = end.nanos - start.nanos; if (duration.seconds < 0 && duration.nanos > 0) { duration.seconds += 1; duration.nanos -= 1000000000; } else if (duration.seconds > 0 && duration.nanos < 0) { duration.seconds -= 1; duration.nanos += 1000000000; } Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. Timestamp start = ...; Duration duration = ...; Timestamp end = ...; end.seconds = start.seconds + duration.seconds; end.nanos = start.nanos + duration.nanos; if (end.nanos < 0) { end.seconds -= 1; end.nanos += 1000000000; } else if (end.nanos >= 1000000000) { end.seconds += 1; end.nanos -= 1000000000; } Example 3: Compute Duration from datetime.timedelta in Python. td = datetime.timedelta(days=3, minutes=10) duration = Duration() duration.FromTimedelta(td) # JSON Mapping In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix "s" (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should be expressed in JSON format as "3.000000001s", and 3 seconds and 1 microsecond should be expressed in JSON format as "3.000001s". - `trigger` GitpodV1PrebuildTrigger — PrebuildTrigger defines when prebuilds should be created for a project. - `dailySchedule` GitpodV1PrebuildTriggerDailySchedule, required — DailySchedule triggers prebuilds once per day at a specified hour. - `hourUtc` integer — hour_utc is the hour of day (0-23) in UTC when the prebuild should start. The actual start time may be adjusted by a few minutes to balance system load. - `technicalDescription` string — technical_description is a detailed technical description of the project This field is not returned by default in GetProject or ListProjects responses 8KB max ## Response `200` Success - GitpodV1CreateProjectResponse - `project` GitpodV1Project — unresolved $ref ## Other responses - `default` — Error ## Changes - **2026-01-09** `3935e467f9c1` — 1 info - added the optional property `project/recommendedEditors` to the response with the `200` status - **2025-12-15** `d62ef4b9187c` — 4 warning, 7 info - removed the request property `environmentClass` - added the new `CLONE_TARGET_MODE_REMOTE_TAG` enum value to the `project/initializer/specs/items/git/targetMode` response property for the response status `200` - added the new `PRINCIPAL_AGENT_EXECUTION` enum value to the `project/metadata/creator/principal` response property for the response status `200` - added the new `PRINCIPAL_AGENT_EXECUTION` enum value to the `project/usedBy/subjects/items/principal` response property for the response status `200` - …7 more - **2025-06-10** `ca9a49ac7fbb` — 2 warning, 2 info - added the new `PRINCIPAL_RUNNER_MANAGER` enum value to the `project/metadata/creator/principal` response property for the response status `200` - added the new `PRINCIPAL_RUNNER_MANAGER` enum value to the `project/usedBy/subjects/items/principal` response property for the response status `200` - added the new optional request property `technicalDescription` - added the optional property `project/technicalDescription` to the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.ProjectService/CreateProject/post.md) --- [API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/b97dcde84128/schema)