Codespaces

GitHub Codespaces

Cloud development environments that work anywhere.

Prerequisites

• GitHub Account: With Codespaces access
• gh CLI: Install from https://cli.github.com/
• Authentication: Run gh auth login

Quick Reference

Core Commands

Machine Types

DevContainer Configuration

Directory Structure

.devcontainer/
+-- devcontainer.json           # Default configuration
+-- web-frontend/
|   +-- devcontainer.json       # Frontend-specific
+-- backend-api/
|   +-- devcontainer.json       # Backend-specific
+-- data-science/
    +-- devcontainer.json       # Data science config

Basic devcontainer.json

{
  "name": "Project Dev Environment",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/devcontainers/features/python:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "GitHub.copilot",
        "ms-python.python"
      ]
    }
  },
  "postCreateCommand": "npm install",
  "forwardPorts": [3000, 5000]
}

Lifecycle Scripts

postCreateCommand

Runs once when container is created:

"postCreateCommand": "npm install && npm run setup"

postStartCommand

Runs every time codespace starts:

"postStartCommand": "npm run dev:services"

postAttachCommand

Runs when VS Code attaches:

"postAttachCommand": "echo 'Welcome! Run npm start to begin.'"

Secrets Management

Setting Secrets

# For a specific repo
gh secret set API_KEY --repo owner/repo

# For Codespaces specifically
gh secret set DB_PASSWORD --app codespaces

# For user (all Codespaces)
gh secret set NPM_TOKEN --user

Using Secrets in devcontainer.json

{
  "containerEnv": {
    "DATABASE_URL": "${localEnv:DATABASE_URL}"
  },
  "secrets": {
    "API_KEY": {
      "description": "API key for external service"
    }
  }
}

Port Forwarding

Automatic Forwarding

{
  "forwardPorts": [3000, 5000, 8080],
  "portsAttributes": {
    "3000": {
      "label": "Frontend",
      "onAutoForward": "openBrowser"
    },
    "5000": {
      "label": "API",
      "onAutoForward": "notify"
    }
  }
}

Manual Forwarding

gh codespace ports forward 3000:3000 -c <codespace-name>

Common Workflows

Quick Start New Feature

# Create codespace for feature branch
gh codespace create -r owner/repo -b feature-branch -m standardLinux

# Open in VS Code
gh codespace code

PR Review in Codespace

# Create codespace from PR
gh codespace create -r owner/repo --branch pr-branch

# Or use the PR directly
gh pr checkout 123
gh codespace create

Share Environment

# Export port with visibility
gh codespace ports visibility 3000:public -c <name>

# Get shareable URL
gh codespace ports -c <name>

Performance Optimization

Prebuilds

Enable prebuilds for faster startup:

// .github/codespaces/prebuild.json
{
  "triggers": {
    "branches": ["main", "develop"],
    "paths": ["package.json", ".devcontainer/**"]
  }
}

Dotfiles Repository

Configure personal dotfiles in GitHub Settings > Codespaces.

Cost Management

Auto-stop Settings

Configure in GitHub Settings > Codespaces:

• Default idle timeout: 30 minutes
• Retention period: 7 days

Best Practices

1. Stop when not in use: gh codespace stop
2. Delete completed work: gh codespace delete
3. Use appropriate machine size: Don't over-provision
4. Enable prebuilds: Faster startup, less billing

Troubleshooting

When to Use This Skill

• Setting up cloud development environments
• Configuring devcontainers for team consistency
• Managing Codespaces via CLI
• Optimizing development environment performance
• Sharing development environments
• PR reviews in isolated environments