GitHub Codespaces Tutorial: Cloud Development Environments with devcontainer.json

Codespaces gives you a ready-to-code VS Code environment in the cloud, configured by your repository. In this lesson you will create a codespace, set it up with devcontainer.json, run Playwright tests, and keep usage under control.

---

☁️ What Is GitHub Codespaces?

Codespaces gives you a complete development environment in the cloud, opened in VS Code in your browser (or in the VS Code desktop app), in seconds. Each codespace is a container running on a GitHub-hosted virtual machine with your repository already cloned and your tools installed.

Benefit	Why it matters
No local setup	Start contributing on any computer, even a Chromebook or a locked-down laptop
Same environment for everyone	“Works on my machine” problems disappear
Configuration as code	A devcontainer.json in the repo defines tools and extensions
Powerful machines	Choose more CPU and memory for heavy builds
Great for training	Learners open a ready-made environment with one click

---

🚀 Create Your First Codespace

1. Open a repository on GitHub.
2. Click the green Code button, then the Codespaces tab.
3. Click Create codespace on main.

A browser tab opens with VS Code, a terminal and your files. Git is already configured with your GitHub identity:

git status
git switch -c feature/try-codespaces
# edit files...
git commit -am "Try Codespaces"
git push -u origin feature/try-codespaces

---

🧰 Configure the Environment with devcontainer.json

Add .devcontainer/devcontainer.json so every codespace starts with the right tools:

{
  "name": "Playwright TypeScript",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:22",
  "postCreateCommand": "npm ci && npx playwright install --with-deps",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-playwright.playwright",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "forwardPorts": [9323]
}

Key	Purpose
image	Base container image (or build with a Dockerfile)
features	Add tools such as the GitHub CLI, Docker or Python with one line each
postCreateCommand	Run once after creation (install dependencies and browsers)
customizations.vscode.extensions	Extensions installed automatically
forwardPorts	Ports to forward to your browser (e.g. a report server)

Commit the file; new codespaces use it. For an existing codespace, run Codespaces: Rebuild Container from the Command Palette.

---

🧪 Running Playwright in a Codespace

Codespaces have no physical screen, so tests run headless, which is exactly how they run in CI. To see results:

• HTML report: run npx playwright show-report --host 0.0.0.0; Codespaces forwards the port (9323) and offers to open it in your browser.
• UI mode: run npx playwright test --ui-host=0.0.0.0 --ui-port=8080 and open the forwarded port 8080.
• Traces: open trace.zip files with npx playwright show-trace or at trace.playwright.dev (Trace Viewer).

---

🔌 Ports, Secrets and Settings

• Ports tab: see forwarded ports, open them in the browser, and choose private (default) or public visibility.
• Codespaces secrets (Settings, Codespaces) store values such as TEST_PASSWORD as environment variables inside your codespaces, separate from Actions secrets (secrets).
• Dotfiles: link a dotfiles repository in your settings to apply your personal shell and Git configuration to every codespace.

---

💸 Managing Codespaces and Cost

• Codespaces stop automatically after a period of inactivity (30 minutes by default) and are deleted after a retention period when stopped.
• Stop or delete them from github.com/codespaces when you finish.
• Choose the smallest machine type that works (2 cores is enough for most test projects).
• Stopped codespaces still use storage; delete ones you no longer need.

---

⚖️ Codespaces vs Local Development vs CI

	Local	Codespaces	CI (GitHub Actions)
Interactive editing	✅	✅	❌
Setup effort	Per machine	Once per repo (devcontainer)	Once per workflow
Cost	Your hardware	Free quota, then usage-based	Free for public repos, minutes for private
Best for	Daily work	Onboarding, training, quick fixes, consistent environments	Automated builds and tests

---

📝 Assignment

1. Open a codespace on one of your repositories, make a change, commit and push it.
2. Add a devcontainer.json for a Playwright project with postCreateCommand and the Playwright extension, and rebuild.
3. Run the tests headless and open the HTML report through a forwarded port.
4. Add a Codespaces secret and print whether it is set (not its value) in the terminal.
5. Stop and delete the codespace from github.com/codespaces.

---

❓ FAQ

🤔 What is GitHub Codespaces?

A cloud development environment that runs VS Code with your repository and tools in a GitHub-hosted container, accessible from the browser or VS Code desktop.

🤔 Is GitHub Codespaces free?

Personal accounts get a monthly free quota of usage; usage beyond it is billed. Organisations can pay for their members.

🤔 What is devcontainer.json?

A configuration file in .devcontainer/ that defines the container image, tools, extensions and setup commands for a codespace or dev container.

🤔 Can I run Playwright tests in Codespaces?

Yes, headless. View the HTML report or UI mode through forwarded ports.

🤔 How do I stop a codespace?

It stops after inactivity automatically, or stop it from the Codespaces menu in VS Code or from github.com/codespaces.

---

🎯 Next Steps

• 🤖 GitHub Copilot for Developers and Testers
• 🏗️ Project 1: Team Collaboration Workflow Simulation
• 📘 Git and GitHub Tutorial: full course