---
name: gitpod-project
description: Gitpod Classic recipe for open-forge. Self-hosted cloud development environments on Kubernetes via Helm chart. AGPL-3.0.
---

# Gitpod (Classic)

Open-source cloud development environment platform — spins up on-demand, pre-configured dev environments (workspaces) in ephemeral Docker containers with VS Code or JetBrains IDEs, defined by a `.gitpod.yml` in each repo. The SaaS product was rebranded to "Ona", but the open-source Classic codebase remains self-hostable. Upstream: <https://github.com/gitpod-io/gitpod>. Official site: <https://www.gitpod.io>.

> ⚠️ **Kubernetes only.** There is no Docker Compose or single-host install path. You need a working Kubernetes cluster before starting.

## Compatible install methods

| Method | Upstream | First-party? | When to use |
|---|---|---|---|
| Helm chart (Kubernetes) | <https://www.gitpod.io/docs/configure/self-hosted/latest/self-hosted> | ✅ | Only supported self-hosting path. Requires Kubernetes cluster ≥ 4 vCPU / 16 GB RAM + domain + wildcard TLS cert. |
| Docker Compose | — | ❌ | **Not available.** There is no official Docker Compose path. |
| DevPod (client-only) | <https://devpod.sh/> | ✅ (sister project) | Simpler alternative — runs dev containers locally or on any cloud VM without a server. No Kubernetes needed. |
| Coder | <https://coder.com/> | ❌ (third-party) | Alternative remote dev platform; supports Docker or Kubernetes. Consider if Kubernetes overhead is too high. |

## Inputs to collect

| Phase | Prompt | Format | Applicability |
|---|---|---|---|
| preflight | "Do you have a running Kubernetes cluster (min 4 vCPU, 16 GB RAM)?" | Confirm / describe cluster | Required — no cluster, no install |
| preflight | "Which Kubernetes distribution / provider?" | Free-text (e.g. GKE, EKS, AKS, k3s, RKE2) | Informs node pool sizing and storage class |
| dns | "What domain will Gitpod be hosted on?" | Free-text (e.g. `gitpod.example.com`) | Gitpod requires a domain — IP-only is unsupported |
| dns | "Do you have a wildcard TLS certificate or cert-manager installed?" | `cert-manager` / `manual wildcard cert` | Gitpod workspaces use `*.ws.<domain>` subdomains — wildcard cert required |
| scm | "Which source code manager to integrate?" | `GitHub` / `GitLab` / `Bitbucket` / `Azure DevOps` / `None (configure later)` | OAuth application must be created in the SCM |
| scm | "OAuth Client ID and Secret for `<scm>`?" | Free-text (sensitive) | Used to authenticate users via SCM |
| storage | "Which object storage backend for workspace images?" | `S3` / `GCS` / `Azure Blob` / `MinIO (self-hosted)` | Gitpod stores workspace snapshots in object storage |

## Software-layer concerns

### Helm chart

Gitpod ships a single Helm chart (the "installer") that deploys all components: the workspace manager, image builder, proxy, dashboard, and supporting services (MySQL, Redis, registry).

```
Helm chart location: https://github.com/gitpod-io/gitpod/tree/main/install/installer
Docs: https://www.gitpod.io/docs/configure/self-hosted/latest/self-hosted
```

### Key config resources (in-cluster)

| Resource | Notes |
|---|---|
| Helm `values.yaml` | Primary configuration; generated by the Gitpod installer CLI |
| `.gitpod.yml` | Per-repository workspace definition (not a server-side config) |
| `gitpod-installer` binary | Used to generate `values.yaml` — download from GitHub releases |

### Key Helm values (selected)

| Helm value | Description |
|---|---|
| `domain` | Root domain for Gitpod (e.g. `gitpod.example.com`) |
| `certificate.name` | TLS secret name in the `gitpod` namespace |
| `authProviders` | SCM OAuth provider config (GitHub, GitLab, Bitbucket, Azure DevOps) |
| `objectStorage.inCluster` | Set to `false` when using external S3/GCS/Azure |
| `database.inCluster` | Set to `false` when using external MySQL |

### Persistent volumes

| Service | PVC | Notes |
|---|---|---|
| MySQL | `gitpod-mysql` | User accounts, workspace metadata — back up regularly |
| Registry | `gitpod-registry` | Built workspace images |
| MinIO (if in-cluster) | `gitpod-minio` | Workspace snapshots |

### Example: generate Helm values with the installer

```bash
# Download the installer for your Gitpod version
GITPOD_VERSION=2023.11.3    # replace with latest from GitHub releases
curl -L "https://github.com/gitpod-io/gitpod/releases/download/${GITPOD_VERSION}/gitpod-installer-linux-amd64" \
  -o gitpod-installer && chmod +x gitpod-installer

# Generate a base values.yaml
./gitpod-installer init > values.yaml

# Edit values.yaml: set domain, auth providers, TLS secret name, storage backend

# Validate config
./gitpod-installer validate cluster --config values.yaml

# Render manifests (inspect before applying)
./gitpod-installer render --config values.yaml --namespace gitpod > gitpod.yaml

# Apply
kubectl apply -f gitpod.yaml
```

Full installation walkthrough: <https://www.gitpod.io/docs/configure/self-hosted/latest/self-hosted>

## Upgrade procedure

```bash
# 1. Download the installer for the new Gitpod version
NEW_VERSION=2024.x.y    # check GitHub releases
curl -L "https://github.com/gitpod-io/gitpod/releases/download/${NEW_VERSION}/gitpod-installer-linux-amd64" \
  -o gitpod-installer-new && chmod +x gitpod-installer-new

# 2. Re-render manifests against existing values.yaml
./gitpod-installer-new render --config values.yaml --namespace gitpod > gitpod-new.yaml

# 3. Apply (rolling update)
kubectl apply -f gitpod-new.yaml

# 4. Monitor rollout
kubectl rollout status deployment -n gitpod
```

Check the release notes before upgrading — some versions require database migration steps.

## Gotchas

- **Kubernetes-only.** There is no Docker Compose path and no single-binary option. If you need a simpler stack, evaluate DevPod (no server required, client-side) or Coder (supports both Docker and Kubernetes).
- **SaaS rebranding.** Gitpod's hosted SaaS is now called "Ona". The self-hosted open-source codebase at `gitpod-io/gitpod` continues under the "Gitpod Classic" name — do not confuse the two.
- **Wildcard TLS is mandatory.** Each running workspace gets a unique subdomain under `*.ws.<domain>`. A single-domain certificate will not work — you need a wildcard cert or cert-manager configured with a wildcard issuer.
- **Minimum cluster size.** 4 vCPU and 16 GB RAM is the stated minimum; production workloads with multiple concurrent users need significantly more. Under-provisioned clusters produce cryptic workspace-start failures.
- **SCM OAuth application required.** Gitpod authenticates users through your SCM (GitHub, GitLab, etc.). You must create an OAuth app in the SCM before install and provide its client ID and secret.
- **In-cluster services are not production-grade.** The default in-cluster MySQL and MinIO are convenient for evaluation but lack backup automation. For production, point Gitpod at an external managed database and object storage.
- **Workspace images are pre-built.** Gitpod builds a workspace Docker image on first use of each repo config. If the image builder component lacks cluster resources, workspace starts will time out.
- **Verify upstream maintenance cadence.** Check the GitHub repo for recent release activity before committing to a production deployment.

## Links

- GitHub: <https://github.com/gitpod-io/gitpod>
- Self-hosting docs: <https://www.gitpod.io/docs/configure/self-hosted/latest/self-hosted>
- Helm installer source: <https://github.com/gitpod-io/gitpod/tree/main/install/installer>
- `.gitpod.yml` reference: <https://www.gitpod.io/docs/references/gitpod-yml>
- License: AGPL-3.0
- Stars: ~12K
- DevPod (simpler alternative, no server): <https://devpod.sh/>
- Coder (alternative, Docker or K8s): <https://coder.com/>
