---
name: codespaces
description: Create, manage, and optimize GitHub Codespaces cloud development environments. Configure devcontainers, manage resources, and streamline cloud-based development. Triggers on codespace, devcontainer, cloud IDE, remote development, development environment, container development.
---

# GitHub Codespaces Skill

> **Cloud development environments that work anywhere**

GitHub Codespaces provides instant, configurable development environments in the cloud. This skill covers creating, managing, and optimizing Codespaces for any project type.

## Prerequisites

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

## Quick Reference

### Core Commands

| Action | Command |
|--------|---------|
| Create codespace | `gh codespace create -r owner/repo` |
| List codespaces | `gh codespace list` |
| Open in VS Code | `gh codespace code -c <name>` |
| Open in browser | `gh codespace view -c <name> -w` |
| SSH into codespace | `gh codespace ssh -c <name>` |
| Stop codespace | `gh codespace stop -c <name>` |
| Delete codespace | `gh codespace delete -c <name>` |

### Machine Types

| Type | vCPUs | RAM | Storage | Best For |
|------|-------|-----|---------|----------|
| Basic | 2 | 8GB | 32GB | Simple projects, docs |
| Standard | 4 | 16GB | 32GB | Most development |
| Large | 8 | 32GB | 64GB | Full-stack, multiple services |
| XL | 16 | 64GB | 128GB | Data science, ML |
| GPU | 4+ | 16GB+ | 64GB+ | ML training, CUDA |

## DevContainer Configuration

### Location Options

```
.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

```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]
}
```

## Environment Profiles

This repository includes pre-configured profiles:

### 1. Standard (Default)
- Node.js + Python
- Common development tools
- GitHub CLI pre-configured
- Good for most projects

### 2. Web Frontend
- Node.js 20 LTS
- npm/yarn/pnpm
- Browser preview
- React/Vue/Angular extensions

### 3. Backend API
- Node.js + Python + Go
- PostgreSQL + Redis
- API testing tools
- Docker-in-Docker

### 4. Data Science
- Python 3.11+
- Jupyter notebooks
- pandas, numpy, scikit-learn
- Optional GPU support

## Lifecycle Scripts

### postCreateCommand
Runs once when container is created:
```json
"postCreateCommand": "npm install && npm run setup"
```

### postStartCommand
Runs every time codespace starts:
```json
"postStartCommand": "npm run dev:services"
```

### postAttachCommand
Runs when VS Code attaches:
```json
"postAttachCommand": "echo 'Welcome! Run npm start to begin.'"
```

## Secrets Management

### Setting Secrets

```bash
# 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

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

## Port Forwarding

### Automatic Forwarding

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

### Manual Forwarding

```bash
# In codespace terminal
gh codespace ports forward 3000:3000 -c <codespace-name>
```

## Performance Optimization

### Prebuilds

Enable prebuilds for faster startup:

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

### Dotfiles Repository

Configure personal dotfiles:
```bash
# In GitHub Settings > Codespaces
# Set dotfiles repository to your-username/dotfiles
```

### Resource Management

```bash
# Check machine type
gh codespace list --json name,machinetype

# Resize codespace
gh codespace edit -c <name> -m largePremiumLinux
```

## Common Workflows

### Quick Start New Feature

```bash
# 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

```bash
# 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

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

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

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Slow startup | Enable prebuilds |
| Out of storage | Delete unused files, increase disk |
| Extension not working | Check devcontainer extensions config |
| Port not accessible | Check forwardPorts configuration |
| Environment variables missing | Verify secrets are set |

## 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

---

## Related Documentation

- [Codespaces Workflow Guide](../../../docs/guides/codespaces-workflow.md)
- [Reference Documentation](./reference.md)
- [Codespaces Manager Agent](../../agents/codespaces-manager.md)
- [DevContainer Configurations](../../../.devcontainer/)