GitHub Codespaces Cheat Sheet

Overview

GitHub Codespaces provides instant cloud-hosted development environments powered by VS Code. Each codespace runs in a Docker container with configurable compute resources, allowing developers to code from any browser or connect via VS Code Desktop or JetBrains Gateway. Codespaces integrates natively with GitHub repositories, pull requests, and Actions.

Codespaces uses the Dev Container specification for configuration, meaning .devcontainer/devcontainer.json files define the environment. It supports prebuilds to cache dependency installation, port forwarding for web services, and dotfiles repositories for personal customization. Organizations can set spending limits and machine type policies.

Installation

Browser Usage

# Open a codespace from any GitHub repo
# Click "Code" > "Codespaces" > "Create codespace on main"

# Direct URL pattern
# https://github.com/codespaces/new?repo=user/repo&ref=main

# Quick create: press . on any repo page for github.dev (lightweight)
# Or press , for a full codespace

GitHub CLI

# Install GitHub CLI
brew install gh

# Create a codespace
gh codespace create --repo user/repo --branch main --machine basicLinux32gb

# List codespaces
gh codespace list

# Open in VS Code
gh codespace code -c <codespace-name>

# Open in browser
gh codespace code -c <codespace-name> --web

# SSH into codespace
gh codespace ssh -c <codespace-name>

# Stop a codespace
gh codespace stop -c <codespace-name>

# Delete a codespace
gh codespace delete -c <codespace-name>

Core Configuration

devcontainer.json

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "GitHub.copilot"
      ],
      "settings": {
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "editor.formatOnSave": true
      }
    }
  },
  "forwardPorts": [3000, 5432],
  "postCreateCommand": "npm install",
  "postStartCommand": "npm run dev &",
  "remoteUser": "node"
}

Machine Types

Machine	vCPUs	RAM	Storage	Use Case
Basic	2	8 GB	32 GB	Light editing, scripting
Standard	4	16 GB	32 GB	General development
Large	8	32 GB	64 GB	Builds, multiple services
XL	16	64 GB	128 GB	Large monorepos, ML

# Create with specific machine type
gh codespace create --repo user/repo --machine largePremiumLinux

# Change machine type (requires restart)
gh codespace edit -c <name> --machine standardLinux32gb

Port Forwarding

{
  "forwardPorts": [3000, 5432, 8080],
  "portsAttributes": {
    "3000": {
      "label": "Application",
      "onAutoForward": "openPreview"
    },
    "5432": {
      "label": "PostgreSQL",
      "onAutoForward": "silent"
    },
    "8080": {
      "label": "API",
      "onAutoForward": "notify",
      "visibility": "public"
    }
  }
}

# CLI port forwarding
gh codespace ports -c <name>
gh codespace ports forward 8080:8080 -c <name>
gh codespace ports visibility 3000:public -c <name>

Configuration

Secrets Management

# Set user secret (available to all your codespaces)
gh secret set MY_API_KEY --user --repos user/repo

# Set organization secret
gh secret set ORG_TOKEN --org myorg --repos myorg/repo

# List secrets
gh codespace secrets list

# Set via GitHub UI
# Settings > Codespaces > Secrets > New Secret

Dotfiles Repository

# Configure in GitHub Settings > Codespaces > Dotfiles
# Point to your dotfiles repository

# The repo should contain:
# install.sh (or setup.sh, bootstrap.sh) — auto-executed
# .bashrc, .zshrc, .gitconfig, .vimrc — symlinked

# Example install.sh
#!/bin/bash
ln -sf ~/dotfiles/.zshrc ~/.zshrc
ln -sf ~/dotfiles/.gitconfig ~/.gitconfig
ln -sf ~/dotfiles/.vimrc ~/.vimrc

Prebuilds

// .devcontainer/devcontainer.json
{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "postCreateCommand": "npm ci && npm run build",
  "updateContentCommand": "npm ci"
}

# Enable prebuilds in repo settings
# Settings > Codespaces > Set up prebuild

# Prebuild configuration options:
# - Trigger on push to specific branches
# - Region availability
# - Template retention

Advanced Usage

Multi-Container Setup

{
  "name": "Full Stack",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000, 5432, 6379],
  "postCreateCommand": "npm install && npm run db:setup"
}

GPU-Enabled Codespaces

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "hostRequirements": {
    "gpu": {
      "count": 1,
      "memory": "16gb"
    }
  },
  "features": {
    "ghcr.io/devcontainers/features/nvidia-cuda:1": {
      "cudaVersion": "12.2"
    }
  }
}

GitHub CLI Codespace Commands

# Create and connect
gh codespace create -r user/repo -b main -m basicLinux32gb
gh codespace code -c <name>

# Copy files to/from codespace
gh codespace cp local-file.txt remote:/workspace/ -c <name>
gh codespace cp remote:/workspace/output.log . -c <name>

# Run command in codespace
gh codespace ssh -c <name> -- "npm test"

# View logs
gh codespace logs -c <name>

# Rebuild codespace
gh codespace rebuild -c <name>

# Export changes to a branch
gh codespace ssh -c <name> -- "git push origin feature-branch"

Lifecycle Management

# List all codespaces with status
gh codespace list --json name,state,machineName,lastUsedAt

# Stop all running codespaces
gh codespace list --json name,state -q '.[] | select(.state == "AVAILABLE") | .name' | \
  xargs -I{} gh codespace stop -c {}

# Delete old codespaces
gh codespace delete --all --days 30

# Set auto-stop timeout (default 30 min)
# GitHub Settings > Codespaces > Default idle timeout

Troubleshooting

Issue	Solution
Codespace slow to start	Enable prebuilds for the repository
Port not accessible	Check port visibility settings and forwarding
Out of storage	Delete unused files, docker system prune, or upgrade machine
Extensions not loading	Check extension IDs, rebuild container
Secrets not available	Verify secret is scoped to the correct repo
Connection dropped	Check network; codespace auto-stops after idle timeout

# Debug inside codespace
cat /workspaces/.codespaces/shared/environment-variables.json
df -h                         # Check disk space
free -m                       # Check memory
docker system df              # Docker disk usage

# Rebuild from scratch
gh codespace rebuild -c <name> --full

# Check creation log
gh codespace logs -c <name>

# Reset VS Code state
# Ctrl+Shift+P > "Developer: Reset State"