All About GitHub Codespaces
- Nathan
- Nov 30
- 6 min read
Overview
A GitHub Codespace acts as your own personal development environment hosted in the cloud. Each Codespace runs inside a special Docker dev container, which in turn runs on an Azure virtual machine. The infrastructure (virtual machine, docker container, etc.) is automatically created and managed for you by GitHub. Once created, you are able to connect to the dev container using a few different methods. Once connected, you can do your standard development work using this cloud-hosted environment.
Codespaces are created per repository, and each Codespace can target a specific Branch, Tag, or Commit (more on this later). Each Codespace runs on its own underlying VM & container. GitHub has a few predefined VM sizes that you can choose from. They range from 2 CPU cores with 8 GB of RAM, to 16 CPU cores with 64 GB of RAM. GitHub bills for Codespaces based on the amount of compute time used as well as the amount of storage used. Note that GitHub personal accounts include a certain amount of free quota for compute time and storage. For more information about billing and VM sizes, please see the docs.
Configuring Dev Containers
Dev containers can be configured using special files that are stored in your repository right alongside your normal code. These config files use a json file extension, and are written in the JSONC format (json with comments). Note: for full details of all the available settings for this file, please see the official specification.
Specifying the default configuration for your repo can be done in 1 of 3 ways:
Create a folder called .devcontainer (notice the leading period) and inside create a file called devcontainer.json
Create a file at the root of your repository called .devcontainer.json (notice the leading period)
Do not create a default config file. In this case, Codespaces will use the default, universal dev container image. This default image comes pre-loaded with many popular language runtimes as well as many popular dev tools. More information about this default image can be found here
If you'd like to provide one or more alternate Codespace configs, then you can do so by creating subfolders under the .devcontainer folder. Note: only 1 level of subfolders is supported. For example, these would be some valid alternate config files:
.devcontainer/alt-config-1/devcontainer.json
.devcontainer/alt-config-2/devcontainer.json
If multiple config files are present, then you will be asked to pick which one to use when creating a new Codespace.
If you are using VS Code, then there is an easy way to quickly create a customized devcontainer.json file. First, you need to install the VS Code extension for Dev Containers from Microsoft. Next, open the VS Code command palette, and run the command for "Dev Containers: Add Dev Container Configuration Files". Then, just go through the automated prompts and select your desired options. When you are done it will create the json file based on the options you selected.
Creating Codespaces
So, now that you have a json configuration file, how do you actually create a new Codespace? There are a few different ways, let's go over them below:
Create with VS Code Desktop
First, install the VS Code extension for GitHub Codespaces. Then, open the Remote Explorer panel and under GitHub Codespaces click on "Create Codespace". You will be prompted to answer some questions, like which Repository to use, which Branch to use, and finally which VM Size to use.
Create with GitHub CLI
You can also use the GitHub CLI to create and manage codespaces. You can simply run the command gh codespace create. You will be prompted to answer some questions, like which Repository to use, which Branch to use, and finally which VM size to use. Optionally, you can also provide many other parameters if you want to customize the command. See the link above for a full list of parameters.
Create on GitHub.com
Lastly, you can create Codespaces from the GitHub.com website. There are various different ways you can accomplish this, let's go over them below:
First, you can go to github.com/codespaces and click on the "New codespace" button. This is very similar to the methods already mentioned above. You must pick a Repository to use, a Branch to use, and a VM Size to use. Note: one unique option with this method is that you also get to pick which Azure Region to use for hosting the VM.
Second, you can go to github.com/codespaces/templates and choose one of the provided templates to use. This will instantly spin up a Codespace with some example code (based on your chosen template). You will not be given any options to select from, it will just be created automatically. Then, it will open VS Code in a new browser tab and it will be loaded with the sample code from that template. From here, you can work on the code and make any changes you want. If you would like to save your code, you can opt to "Publish" it to a repository of your choosing.
Third, if you go to a repository you will see the "Code" button towards the upper-right. Click on that and then click on the "Codespaces" tab, where you will then see a "Create codespace" button.
It is important to note that this option is context aware. If you are currently viewing the main branch, then you'll see "Create codespace on main". If you are currently viewing the develop branch, then you'll see "Create codespace on develop". Likewise, this works for Tags and individual Commits as well.
Connecting to Codespaces
At this point you know how to create a Codespace. Next, let's discuss how to connect to it and start using it.
Open in VS Code desktop | Open in VS Code web | Open in JupyterLab | Connect via SSH | |
VS Code Desktop | ✅ | ✅ | ||
GitHub CLI | ✅ | ✅ | ✅ | ✅ |
GitHub.com | ✅ | ✅ | ✅ |
1 - Connect with VS Code Desktop
If you haven't done so already, install the VS Code extension for GitHub Codespaces. Then, open the Remote Explorer panel and under GitHub Codespaces you will see the list of existing Codespaces that you have created. From here, you can connect to a Codespace in 2 different ways:
1A - Connect with VS Code desktop: As shown in the above photo, you can simply click the "Connect" button on your chosen Codespace. This will use your local VS Code and will connect it to your Codespace hosted in the cloud. Your local VS Code terminal will also be connected to the Dev container, allowing you to run terminal commands directly on the container. When you are finished, you can open the Remote Explorer panel and choose the "Disconnect" icon.
1B - Connect with VS Code web: As shown in the above photo, you could right-click on your chosen Codespace and click "Open in Browser". Doing this will open VS Code in a new browser tab where it will be connected to your chosen Codespace.
2 - Connect with GitHub CLI
2A - Connect with VS Code desktop: This is the same as method 1A. Just run the command gh codespace code and select your Codespace. After that, your local VS Code will be connected to your Codespace. Optionally, you can also provide some extra parameters if you want to customize the command. See the link above for a full list of parameters.
2B - Connect with VS Code web: This is the same as method 1B. Just run the command gh codespace code --web and select your Codespace. Doing this will open VS Code in a new browser tab where it will be connected to your chosen Codespace. Optionally, you can also provide some extra parameters if you want to customize the command. See the link above for a full list of parameters.
2C - Connect with JupyterLab web: Run the command gh codespace jupyter and select your Codespace. Doing this will open a new browser tab running the JupyterLab web interface and it will be connected to your Codespace. For this to work, your dev container must have the JupyterLab application pre-installed. This is included if you are using the default, universal dev container image. For more info, see the docs.
2D - Connect with SSH: Run the command gh codespace ssh and select your Codespace. Doing this will open an SSH connection directly to your dev container. This will automatically create a public/private SSH key pair in the ~/.ssh directory if you do not have an existing valid key pair. For this to work, your dev container must an SSH Server pre-installed. This is included if you are using the default, universal dev container image. See the link above for full details of using this method.
3 - Connect with GitHub.com
Go to github.com/codespaces to see your list of existing Codespaces. From here, you can connect to a Codespace in 3 different ways:
3A - Connect with VS Code desktop. This is the same as 1A and 2A. For this, choose the option "Open in Visual Studio Code"
3B - Connect with VS Code web. This is the same as 1B and 2B. For this, choose the option "Open in Browser"
3C - Connect with JupyterLab web. This is the same as 2C. For this, choose the option "Open in JupyterLab"