Configuring Codespaces for your project
You can set up a default configuration for every new codespace for your repository to ensure that contributors have all the tools and settings they need in their online development environment.
People with write permissions to a repository can create or edit the default codespace configuration.
Codespaces is available for user accounts using GitHub Free or GitHub Pro. For more information, see "GitHub's products."
Note: Codespaces is currently in limited public beta and subject to change. During the beta period, GitHub does not make any guarantees about the availability of Codespaces. For more information about joining the beta, see "About Codespaces."
You can create a default codespace configuration for your repository that determines the environment of every new codespace anyone creates for that repository. The configuration can include frameworks, tools, extensions, and port forwarding.
You can also personalize aspects of the codespace environment for any codespace that your account creates. Personalization can include shell preferences and additional tools. Your
dotfiles personalization is applied before a repository's default codespace configuration. For more information, see "Personalizing Codespaces for your account."
You can create a default codespace configuration using a pre-built container configuration for your project type, or you can create a custom configuration specific to your project's needs.
Codespaces uses settings contained in a file named
devcontainer.json in the root of the repository or in a
.devcontainer folder. You can use
devcontainer.json to set default settings for the entire codespace environment, including the Visual Studio Code editor, but you can also set editor-specific settings in a file named
Changes to a repository's codespace configuration apply only to every new codespace and do not affect any existing codespace.
You can use any pre-built container configuration for Visual Studio Code that is available in the
vscode-dev-containers repository. Pre-built container definitions include a common configuration for a particular project type, and can help you quickly get started with a configuration that already has the appropriate container options, Visual Studio Code settings, and Visual Studio Code extensions that should be installed.
- Clone or download the
- In the
vscode-dev-containersrepository, navigate to the
- From the
.devcontainerfolder to the root of your project's repository.
- Commit and push the new configuration to your project's repository on GitHub.
Each new codespace created from a branch which contains the
.devcontainer folder will be configured according to the folder's contents. For more information, see "Creating a codespace."
If none of the pre-built configurations meet your needs, you can create a custom configuration by adding a
devcontainer.json file to the root of your repository or a
.devcontainer folder. In the file, you can use supported configuration keys to specify aspects of the codespace's environment, like which Visual Studio Code extensions will be installed.
When you configure editor settings for Visual Studio Code, there are three scopes available: Workspace, Remote [Codespaces], and User. If a setting is defined in multiple scopes, Workspace settings take priority, then Remote [Codespaces], then User.
You can define default editor settings for Visual Studio Code in two places.
- Editor settings defined in
.vscode/settings.jsonare applied as Workspace-scoped settings in the codespace.
- Editor settings defined in the
devcontainer.jsonare applied as Remote [Codespaces]-scoped settings in the codespace.
You can use configuration keys supported by Codespaces in
For more information about the available settings for
devcontainer.json, see devcontainer.json reference in the Visual Studio Code documentation.