GitHub Codespaces is an instant, cloud-based development environment that uses a container to provide you with common languages, tools, and utilities for development. GitHub Codespaces is also configurable, allowing you to create a customized development environment for your project. By configuring a custom development environment for your project, you can have a repeatable codespace configuration for all users of your project.
There are a number of entry points to create a codespace.
- From your repository for new feature work.
- From an open pull request to explore work-in-progress.
- From a commit in the repository's history to investigate a bug at a specific point in time.
- From Visual Studio Code.
Your codespace can be ephemeral if you need to test something or you can return to the same codespace to work on long-running feature work. For more information, see "Creating a codespace."
Once you've selected the option to create a new codespace, and optionally selected from the various configuration options for your codespace, some steps happen in the background before the codespace is available to you.
When you create a codespace, a shallow clone of your repository is made on a Linux virtual machine that is both dedicated and private to you. Having a dedicated VM ensures that you have the entire set of compute resources from that machine available to you. If necessary, this also allows you to have full root access to your container.
GitHub Codespaces uses a container as the development environment. This container is created based on the configurations that you can define in a
devcontainer.json file and/or Dockerfile in your repository. If you don't configure a container, GitHub Codespaces uses a default image, which has many languages and runtimes available. For information on what the default image contains, see the
Note: If you want to use Git hooks in your codespace and apply anything in the git template directory to your codespace, then you must set up hooks during step 4 after the container is created.
Since your repository is cloned onto the host VM before the container is created, anything in the git template directory will not apply in your codespace unless you set up hooks in your
devcontainer.json configuration file using the
postCreateCommand in step 4. For more information, see "Step 4: Post-creation setup."
When your container has been created and any other initialization has run, you'll be connected to your codespace. You can connect to it through the web or via VS Code, or both, if needed.
Once you are connected to your codespace, your automated setup may continue to build based on the configuration you specified in your
devcontainer.json file. You may see
If you want to use Git hooks in your codespace, set up hooks using the
devcontainer.json lifecycle scripts, such as
postCreateCommand. For more information, see the
devcontainer.json reference in the VS Code documentation.
If you have a public dotfiles repository for GitHub Codespaces, you can enable it for use with new codespaces. When enabled, your dotfiles will be cloned to the container and the install script will be invoked. For more information, see "Personalizing GitHub Codespaces for your account."
Finally, the entire history of the repository is copied down with a full clone.
During post-creation setup you'll still be able to use the integrated terminal and make edits to your files, but take care to avoid any race conditions between your work and the commands that are running.
As you develop in your codespace, it will save any changes to your files every few seconds. Your codespace will keep running for 30 minutes after the last activity. After that time it will stop running but you can restart it from either from the existing browser tab or the list of existing codespaces. File changes from the editor and terminal output are counted as activity and so your codespace will not stop if terminal output is continuing.
Note: Changes in a codespace in VS Code are not saved automatically, unless you have enabled Auto Save.
To stop your codespace you can use the Visual Studio Code Command Palette (Shift+Command+P (Mac) / Ctrl+Shift+P (Windows/Linux)). If you exit your codespace without running the stop command (for example, closing the browser tab), or if you leave the codespace running without interaction, the codespace and its running processes will continue until a window of inactivity occurs, after which the codespace will stop. By default, the window of inactivity is 30 minutes.
When you close or stop your codespace, all uncommitted changes are preserved until you connect to the codespace again.
Port forwarding gives you access to TCP ports running within your codespace. For example, if you're running a web application on port 4000 within your codespace, you can automatically forward that port to make the application accessible from your browser.
Port forwarding determines which ports are made accessible to you from the remote machine. Even if you do not forward a port, that port is still accessible to other processes running inside the codespace itself.
When an application running inside GitHub Codespaces outputs a port to the console, GitHub Codespaces detects the localhost URL pattern and automatically forwards the port. You can click on the URL in the terminal or in the toast message to open the port in a browser. By default, GitHub Codespaces forwards the port using HTTP. For more information on port forwarding, see "Forwarding ports in your codespace."
While ports can be forwarded automatically, they are not publicly accessible to the internet. By default, all ports are private, but you can manually make a port available to your organization or public, and then share access through a URL. For more information, see "Sharing a port."
Running your application when you first land in your codespace can make for a fast inner dev loop. As you edit, your changes are automatically saved and available on your forwarded port. To view changes, go back to the running application tab in your browser and refresh it.
Git is available by default in your codespace and so you can rely on your existing Git workflow. You can work with Git in your codespace either via the Terminal or by using VS Code's source control UI. For more information, see "Using source control in your codespace"
You can create a codespace from any branch, commit, or pull request in your project, or you can switch to a new or existing branch from within your active codespace. Because GitHub Codespaces is designed to be ephemeral, you can use it as an isolated environment to experiment, check a teammate's pull request, or fix merge conflicts.
You can create more than one codespace per repository or even per branch. However, there are limits to the number of codespaces you can create, and the number of codespaces you can run at the same time. If you reach the maximum number of codespaces and try to create another, a message is displayed telling you that you must remove an existing codespace before you can create a new one.
Note: Commits from your codespace will be attributed to the name and public email configured at https://github.com/settings/profile. A token scoped to the repository, included in the environment as
GITHUB_TOKEN, and your GitHub credentials will be used to authenticate.
Using VS Code in your codespace gives you access to the Visual Studio Code Marketplace so that you can add any extensions you need. For information on how extensions run in GitHub Codespaces, see Supporting Remote Development and GitHub Codespaces in the VS Code documentation.
If you already use VS Code, you can use Settings Sync to automatically sync extensions, settings, themes, and keyboard shortcuts between your local instance and any codespaces you create.