Skip to main content

Codespaces lifecycle

You can develop in a GitHub Codespaces environment and maintain your data throughout the entire codespace lifecycle.

GitHub Codespaces 可用于使用 GitHub Team 或 GitHub Enterprise Cloud 的组织。 GitHub Codespaces 也可作为受限的 beta 版本提供给使用 GitHub Free 和 GitHub Pro 计划的个人用户。 有关详细信息,请参阅“GitHub 的产品”。

About the lifecycle of a codespace

The lifecycle of a codespace begins when you create a codespace and ends when you delete it. You can disconnect and reconnect to an active codespace without affecting its running processes. You may stop and restart a codespace without losing changes that you have made to your project.

Creating a codespace

When you want to work on a project, you can choose to create a new codespace or open an existing codespace. You might want to create a new codespace from a branch of your project each time you develop in GitHub Codespaces or keep a long-running codespace for a feature. For more information, see "Creating a codespace."

可以创建的 codespace 数量和可以同时运行的 codespace 数量受到限制。 这些限制因多种因素而异。 如果达到最大 codespace 数并尝试创建另一个 codespace,则会显示一条消息,告知你必须删除现有 codespace,然后才能创建新的 codespace。 Similarly, if you reach the maximum number of active codespaces and you try to start another, you are prompted to stop one of your active codespaces.

If you choose to create a new codespace each time you work on a project, you should regularly push your changes so that any new commits are on GitHub. If you choose to use a long-running codespace for your project, you should pull from your repository's default branch each time you start working in your codespace so that your environment has the latest commits. This workflow is very similar to if you were working with a project on your local machine.

To speed up codespace creation, repository administrators can enable GitHub Codespaces prebuilds for a repository. For more information, see "About GitHub Codespaces prebuilds."

Saving changes in a codespace

When you connect to a codespace through the web, auto-save is enabled automatically for the web editor and configured to save changes after a delay. When you connect to a codespace through Visual Studio Code running on your desktop, you must enable auto-save. For more information, see Save/Auto Save in the Visual Studio Code documentation.

If you want to save your changes in the git repository on the codespace's file system, commit them and push them to a remote branch.

If you have unsaved changes, your editor will prompt you to save them before exiting.

Codespaces timeouts

If you leave your codespace running without interaction, or if you exit your codespace without explicitly stopping it, the codespace will timeout after a period of inactivity and stop running. By default, a codespace will timeout after 30 minutes of inactivity, but you can customize the duration of the timeout period for new codespaces that you create. For more information about setting the default timeout period for your codespaces, see "Setting your timeout period for GitHub Codespaces." For more information about stopping a codespace, see "Stopping a codespace."

When a codespace times out, your data is preserved from the last time your changes were saved. For more information, see "Saving changes in a codespace."

Rebuilding a codespace

You can rebuild your codespace to restore a clean state as if you had created a new codespace. For most uses, you can create a new codespace as an alternative to rebuilding a codespace. You are most likely to rebuild a codespace to implement changes to your dev container. When you rebuild a codespace, any Docker containers, images, volumes, and caches are cleaned, then the codespace is rebuilt.

If you need any of this data to persist over a rebuild, you can create, at the desired location in the container, a symbolic link (symlink) to the persistent directory. For example, in your .devcontainer directory, you can create a config directory that will be preserved across a rebuild. You can then symlink the config directory and its contents as a postCreateCommand in your devcontainer.json file.

{
    "image": "mcr.microsoft.com/vscode/devcontainers/base:alpine",
    "postCreateCommand": ".devcontainer/postCreate.sh"
}

In the example postCreate.sh file below, the contents of the config directory are symbolically linked to the home directory.

#!/bin/bash
ln -sf $PWD/.devcontainer/config $HOME/config && set +x

Stopping a codespace

You can stop a codespace at any time. When you stop a codespace, any running processes are stopped and the terminal history is cleared. Any saved changes in your codespace will still be available when you next start it. If you do not explicitly stop a codespace, it will continue to run until it times out from inactivity. For more information, see "Codespaces timeouts."

Only running codespaces incur CPU charges; a stopped codespace incurs only storage costs.

You may want to stop and restart a codespace to apply changes to it. For example, if you change the machine type used for your codespace, you will need to stop and restart it for the change to take effect. You can also stop your codespace and choose to restart or delete it if you encounter an error or something unexpected. For more information, see "Stopping and starting a codespace."

Deleting a codespace

You can create a codespace for a particular task and then safely delete the codespace after you push your changes to a remote branch.

If you try to delete a codespace with unpushed git commits, your editor will notify you that you have changes that have not been pushed to a remote branch. You can push any desired changes and then delete your codespace, or continue to delete your codespace and any uncommitted changes. You can also export your code to a new branch without creating a new codespace. For more information, see "Exporting changes to a branch."

Codespaces that have been stopped and remain inactive for a specified period of time will be deleted automatically. By default, inactive codespaces are deleted after 30 days, but you can customize your codespace retention period. For more information, see "Configuring automatic deletion of your codespaces."

You will be charged for the storage of all your codespaces. When you delete a codespace, you will no longer be charged.

For more information on deleting a codespace, see "Deleting a codespace."

Losing the connection while using Codespaces

GitHub Codespaces is a cloud-based development environment and requires an internet connection. If you lose connection to the internet while working in a codespace, you will not be able to access your codespace. However, any uncommitted changes will be saved. When you have access to an internet connection again, you can connect to your codespace in the exact same state that it was left in. If you have an unstable internet connection, you should commit and push your changes often.

If you know that you will often be working offline, you can use your devcontainer.json file with the "Visual Studio Code Remote - Containers" extension to build and attach to a local development container for your repository. For more information, see Developing inside a container in the Visual Studio Code documentation.