Skip to main content
The GitHub Codespaces lifecycle describes the journey of a cloud-hosted development environment from provisioning to termination. Understanding this lifecycle helps you manage costs, protect work, and ensure reliable developer workflows.
The image shows a diagram of the lifecycle of a codespace, highlighting creation, persistence, saving work, and deletion, along with actions like creating, stopping, deleting, and rebuilding a codespace.

​
Quick overview: lifecycle phases

  1. Provisioning (creation) — a VM and persistent storage are allocated; the development container image is built or pulled; connections and initialization run.
  2. Active (connected) — you work in the Codespace, running terminals and services.
  3. Idle / Stopped — compute is halted to save costs while persistent disk retains files.
  4. Rebuild — the environment can be rebuilt from the repository configuration.
  5. Deletion — VM and persistent storage are removed; data cannot be recovered.

​
Provisioning (creation)

When you create a Codespace, GitHub performs several backend steps to prepare a reproducible development environment:
  • Resource allocation: a virtual machine plus dedicated persistent disk are provisioned.
  • Containerization: the devcontainer image is built or pulled using your repository’s configuration (devcontainer.json, Dockerfile).
  • Connection setup: a secure channel is established between your client (browser or VS Code) and the VM.
  • Post-creation configuration: setup scripts and extensions run to install dependencies and apply custom settings.
Recommendations:
  • Keep your devcontainer.json and Dockerfiles small and cache-friendly to reduce creation and rebuild times.
  • Use prebuilt images where available to speed provisioning.

​
Operational states: connected, disconnected, stopped

Codespaces offers flexible states so you can pause and resume work without losing progress:
  • Disconnecting preserves running processes but continues billing for the VM.
  • Stopping conserves compute (and costs) while preserving files on disk.
  • Rebuilding re-applies the repository-defined configuration and can refresh a corrupted or outdated environment.
The image shows a circular lifecycle diagram describing different stages related to "Codespace" such as creation, stopping, rebuilding, and deleting. On the left, there's a list highlighting "Persistence" among other stages like creation and deletion.
Set automatic stop timeouts for idle Codespaces to reduce costs. Organizations and users can configure stop timeouts so idle Codespaces are automatically stopped after a configured period.

​
Saving and synchronizing your work

Files you edit inside a Codespace are stored on that Codespace’s persistent disk for the lifetime of the environment. Important points:
  • Local changes on the Codespace disk exist only in that Codespace until you record them in Git and push to the remote repository.
  • The integrated web editor has autosave enabled by default. When using the VS Code desktop client, enable autosave in VS Code or ensure you save files before committing.
  • The default workspace path inside a Codespace is /workspaces/<repository-name> — use that path when running scripts that expect the repository root.
Example Git workflow to make work permanent and shareable:
Tip: commit frequently and push before stopping or deleting a Codespace to avoid accidental data loss.

​
Deletion and end of lifecycle

Deletion is final: when a Codespace is deleted, its VM and persistent storage are removed and cannot be recovered.
  • You can create multiple Codespaces per branch but watch account and organization limits — you may need to delete older Codespaces when limits are reached.
  • Consider exporting or merging important changes into branches or pull requests before deleting an environment.
The image shows a diagram illustrating the lifecycle of a Codespace, including stages like creation, rebuilding, stopping, and deletion. A circular flowchart and a sidebar with labeled steps are present.
Before stopping or deleting a Codespace, verify that all necessary work has been committed and pushed to the remote repository. Unpushed changes that exist only on the Codespace will be lost upon deletion.

Watch Video