Zum Inhalt springen
1337skills 1337skills - Referenzen

Gitpod Cheat Sheet

Overview

Gitpod is a cloud development environment platform that spins up automated, pre-configured dev environments from any Git context. By defining a .gitpod.yml file in your repository, Gitpod provisions a full Linux workspace with the correct tools, dependencies, and services — ready to code within seconds. It supports VS Code (browser and desktop) and JetBrains IDEs.

Gitpod can be used as a SaaS service (gitpod.io) or self-hosted via Gitpod Flex. It integrates with GitHub, GitLab, and Bitbucket, and supports prebuilds that continuously build workspace images so new environments start instantly rather than waiting for dependency installation.

Installation

Browser Usage

# Prefix any Git URL to open in Gitpod
# https://gitpod.io/#https://github.com/user/repo

# Open specific branch
# https://gitpod.io/#https://github.com/user/repo/tree/feature-branch

# Open specific PR
# https://gitpod.io/#https://github.com/user/repo/pull/42

Gitpod CLI

# Install Gitpod CLI
brew install gitpod-io/tap/gitpod

# Login
gitpod login

# Create workspace from repo
gitpod workspace create https://github.com/user/repo

# List workspaces
gitpod workspace list

# Stop a workspace
gitpod workspace stop <workspace-id>

# Delete a workspace
gitpod workspace delete <workspace-id>

Inside a Workspace

# Gitpod CLI (available in every workspace)
gp version

# Open a file in the editor
gp open src/main.ts

# Open a URL/preview
gp preview http://localhost:3000

# Expose a port
gp ports expose 8080

# Get workspace URL
gp url
gp url 3000

Core Configuration

.gitpod.yml

image: gitpod/workspace-full

tasks:
  - name: Install & Build
    init: |
      npm install
      npm run build
    command: npm run dev

  - name: Database
    command: |
      docker run -d --name postgres \
        -e POSTGRES_PASSWORD=dev \
        -p 5432:5432 postgres:16
      gp ports await 5432
      npm run db:migrate

ports:
  - port: 3000
    onOpen: open-preview
    visibility: public
  - port: 5432
    onOpen: ignore
    visibility: private

vscode:
  extensions:
    - dbaeumer.vscode-eslint
    - esbenp.prettier-vscode
    - bradlc.vscode-tailwindcss

Custom Docker Image

# .gitpod.yml
image:
  file: .gitpod.Dockerfile
# .gitpod.Dockerfile
FROM gitpod/workspace-full

# Install custom tools
RUN brew install jq yq bat fd

# Install specific Node version
RUN bash -c ". /home/gitpod/.nvm/nvm.sh && nvm install 20 && nvm alias default 20"

# Install Python packages
RUN pip install poetry black ruff

# Install system packages
USER root
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*
USER gitpod

Task Configuration

Task Lifecycle

tasks:
  # init: runs during prebuild (cached)
  # before: runs before init and command
  # command: runs when workspace starts

  - name: Backend
    before: |
      export DATABASE_URL=postgres://localhost/myapp
    init: |
      pip install -r requirements.txt
      python manage.py migrate
    command: python manage.py runserver 0.0.0.0:8000

  - name: Frontend
    init: npm ci
    command: npm run dev

  - name: Worker
    command: |
      gp ports await 5432
      celery -A myapp worker -l info

Environment Variables

# .gitpod.yml
tasks:
  - name: Dev Server
    env:
      NODE_ENV: development
      API_URL: http://localhost:8000
    command: npm run dev
# Set persistent env vars via CLI
gp env DATABASE_URL=postgres://localhost/myapp
gp env -e SECRET_KEY=mysecret

# Set org-wide variable (Gitpod dashboard)
# Settings > Variables > New Variable

# Access in workspace
echo $DATABASE_URL

Port Configuration

ports:
  - port: 3000
    onOpen: open-preview    # open-browser, open-preview, ignore, notify
    visibility: public      # public, private
    name: Frontend
    description: Next.js dev server

  - port: 8000
    onOpen: notify
    visibility: private
    name: API Server

  - port: 5432
    onOpen: ignore
    visibility: private
    name: PostgreSQL

  - port: 6379
    onOpen: ignore
    visibility: private

  # Port range
  - port: 9000-9100
    onOpen: ignore
# CLI port management
gp ports list
gp ports expose 8080
gp ports visibility 3000:public
gp ports await 5432
gp url 3000

Advanced Usage

Prebuilds

# .gitpod.yml
github:
  prebuilds:
    master: true
    branches: true
    pullRequests: true
    pullRequestsFromForks: false
    addCheck: true
    addBadge: true
    addComment: false

Multi-Repository Workspaces

# .gitpod.yml
additionalRepositories:
  - url: https://github.com/org/shared-lib
    checkoutLocation: shared-lib
  - url: https://github.com/org/api-specs
    checkoutLocation: api-specs

tasks:
  - name: Setup
    init: |
      cd /workspace/shared-lib && npm install
      cd /workspace/main-repo && npm install

Docker Compose in Gitpod

# .gitpod.yml
image: gitpod/workspace-full

tasks:
  - name: Services
    init: docker compose pull
    command: docker compose up -d

  - name: App
    command: |
      docker compose up -d
      gp ports await 5432
      npm run dev

Workspace Snapshots and Sharing

# Create a snapshot of current workspace state
gp snapshot create

# Share workspace (read-only or full access)
# Use the Share button in Gitpod dashboard

# Open someone else's snapshot
# https://gitpod.io/#snapshot/<snapshot-id>

JetBrains IDE Support

# .gitpod.yml
jetbrains:
  intellij:
    plugins:
      - com.intellij.plugins.watcher
    prebuilds:
      version: stable
  goland:
    plugins:
      - com.intellij.plugins.watcher

Troubleshooting

IssueSolution
Workspace takes long to startEnable prebuilds for init tasks
Ports not accessibleCheck gp ports list and visibility settings
Docker not workingUse gitpod/workspace-full image (includes Docker)
File changes lostCommit/push before timeout; check workspace auto-stop settings
Custom image build failsTest with docker build -f .gitpod.Dockerfile . locally
Extensions not installingVerify extension IDs match VS Code marketplace
# Debug workspace
gp top                    # Resource usage
gp tasks list             # List task terminals
gp info                   # Workspace info

# Restart a task
# Click the terminal tab and restart

# Check logs
cat /var/log/gitpod/*.log

# Reset workspace
# Stop and restart from dashboard

# Validate .gitpod.yml
gp validate