Personalizing GitHub Codespaces for your account

About personalizing Codespaces

When using any development environment, customizing the settings and tools to your preferences and workflows is an important step. GitHub Codespaces allows for two main ways of personalizing your codespaces.

• Settings Sync - You can synchronize your Visual Studio Code settings between the desktop application and the VS Code web client.
• Dotfiles – You can use a dotfiles repository to specify scripts, shell preferences, and other configurations.

GitHub Codespaces personalization applies to any codespace you create.

Project maintainers can also define a default configuration that applies to every codespace for a repository, created by anyone. For more information, see "Introduction to dev containers."

Settings Sync

Settings Sync allows you to synchronize configurations such as settings, keyboard shortcuts, snippets, extensions, and UI state across machines and instances of VS Code. For more information, see Settings Sync in the VS Code documentation.

When you enable Settings Sync in an instance of VS Code, such as the VS Code desktop application on your laptop, your settings for that instance are stored in the cloud. From the cloud, the settings are pulled into all new codespaces at the point of creation, and continuously synced to any existing codespaces in which Settings Sync is enabled.

Whether Settings Sync is enabled by default in a codespace depends on your existing settings and on whether you open the codespace in the browser or in the VS Code desktop application.

• If you open a codespace in the browser, Settings Sync is always disabled at first. This means the transfer of settings takes place in one direction and at one time only: GitHub Codespaces pulls the settings stored in the cloud into the codespace at the point of creation, but any updates you make to the settings in the codespace are not propagated to the cloud, so are not reflected in any other codespaces. Equally, any updates you make to your settings elsewhere are not reflected in your codespace.
• If you open a codespace in the VS Code desktop application, Settings Sync remains enabled in the codespace if you have previously enabled it for the application. Any updates you make to your settings are pushed to cloud, so are reflected in new codespaces and any existing codespaces in which Settings Sync is enabled. If you make updates to your settings in other VS Code instances where Settings Sync is enabled, these updates are reflected in your codespace.

If you're working in a codespace where Settings Sync is disabled, you can enable Settings Sync to push changes you have made to your settings to the cloud, or pull in the latest changes to your settings you have made elsewhere.

Enabling Settings Sync

1. In VS Code, at the bottom of the Activity Bar, select and click Turn on Settings Sync…

2. In the dropdown, select the settings you want to sync.

   

3. Click Sign in & Turn on, then select the account to which you want your settings to be synced.

When you have signed in, the VS Code instance you're working in will immediately be updated to display the latest synced settings.

Disabling Settings Sync

You can disable Settings Sync to stop syncing settings to and from an instance of VS Code.

By default, when you disable Settings Sync, new codespaces continue to use the settings cached from the last time your settings were pushed to the cloud. If your codespaces are still being created with cached settings, and you want to return to using the default VS Code settings in your codespaces, you can clear the cache in the cloud when you disable Settings Sync.

1. If Settings Sync is currently disabled in your instance of VS Code, you must first enable it. For instructions, see "Personalizing GitHub Codespaces for your account."

2. At the bottom of the Activity Bar, select and click Settings Sync is On.

3. In the dropdown, click Settings Sync: Turn Off.

   

4. To clear your cached settings, in the dialog, select Turn off sync on all your devices and clear the data from the cloud.

   

5. Click Turn off.

Dotfiles

Dotfiles are files and folders on Unix-like systems starting with . that control the configuration of applications and shells on your system. You can store and manage your dotfiles in a repository on GitHub. For advice and tutorials about what to include in your dotfiles repository, see GitHub does dotfiles.

Your dotfiles repository might include your shell aliases and preferences, any tools you want to install, or any other codespace personalization you want to make.

You can configure GitHub Codespaces to use dotfiles from any repository you own by selecting that repository in your personal GitHub Codespaces settings.

When you create a new codespace, GitHub clones your selected dotfiles repository to the codespace environment, and looks for one of the following files to set up the environment.

• install.sh
• install
• bootstrap.sh
• bootstrap
• script/bootstrap
• setup.sh
• setup
• script/setup

If none of these files are found, then any files or folders in your selected dotfiles repository starting with . are symlinked to the codespace's ~ or $HOME directory.

Any changes to your selected dotfiles repository will apply only to each new codespace, and do not affect any existing codespace.

Enabling your dotfiles repository for Codespaces

You can use your selected dotfiles repository to personalize your GitHub Codespaces environment. Once you choose your dotfiles repository, you can add your scripts, preferences, and configurations to it. You then need to enable your dotfiles from your personal GitHub Codespaces settings page.

1. In the upper-right corner of any page, click your profile photo, then click Settings.

   

2. In the "Code, planning, and automation" section of the sidebar, click Codespaces.

3. Under "Dotfiles", select Automatically install dotfiles so that GitHub Codespaces automatically installs your dotfiles into every new codespace you create.

   

4. Use the dropdown to choose the repository you want to install dotfiles from.

   

You can add further script, preferences, configuration files to your dotfiles repository or edit existing files whenever you want. Changes to settings will only be picked up by new codespaces.

If your codespace fails to pick up configuration settings from dotfiles, see "Troubleshooting personalization options for GitHub Codespaces."

Other available settings

You can also personalize GitHub Codespaces using additional options in your personal settings:

• To enable GPG verification, see "Managing GPG verification for GitHub Codespaces."
• To set your editor, see "Setting your default editor for GitHub Codespaces."
• To set how long a codespace can remain unused before it is automatically stopped, see "Setting your timeout period for GitHub Codespaces."
• To set the period for which your unused codespaces are retained, see "Configuring automatic deletion of your codespaces."
• To set your default region, see "Setting your default region for GitHub Codespaces."

Further reading

• "Creating a new repository"
• "Deep dive into GitHub Codespaces"