Repository navigation
Exercise: Code with Codespaces #1
Description
Activity
Step 1: Start a codespace and push some code
What's the big deal about Codespaces?
A codespace is a development environment hosted in the cloud, defined by configuration files in your repository. This creates a repeatable development environment tailored specifically to the project that simplifies developer onboarding and avoids the famous phrase "It works on my machine!" 😎
Each codespace follows the Dev Container specification and is hosted by GitHub as a Docker container.
But don't worry! You don't need to know Docker or even have it installed on your machine!
Tip
Since the Dev Container configuration is part of the repository, you can also use it locally with your own Docker host. Nice!
A Codespace has several advantages/features compared to local development. To name a few:
- Start a codespace directly from the repository page.
- Develop in the browser. No IDE installation required.
- Option to use a local install of VS Code to link to the remote Codespace.
- Preconfigure everything you need to run the project:
- Add features to install common development needs.
- Run scripts at various steps of the codespace lifecycle (e.g install python/npm packages).
- Setup VS Code settings and extensions to match the project needs.
- Fast internet access (since the container is in the datacenter).
Tip
Codespaces are even useful in short-lived situations like reviewing a pull request. No need to verify you have the right setup to test out the incoming code changes.
Let's get started! We'll start up a Codespace, run the application, make a change, and push it. Like normal development! 🤓
⌨️ Activity: Start a codespace
-
Open a second tab and navigate to this repository. Ensure you are on the Code tab.
-
Above the files list on the right, click the green <> Code button.
-
Select the Codespaces tab and click the Create codespace on main button. A new window will open running VS Code and it will connect to the remote Codespace. Wait a few minutes for the codespace to be created.
-
Look in the bottom left of the VS Code window see the remote connection.
Tip
GitHub uses the universal Codespace image if the repository doesn't include a configuration. It includes several useful and commonly used tools.
⌨️ Activity: Run the application
-
Ensure you are in the VS Code Codespace.
-
In the left sidebar, select the file Explorer tab and open the file
src/hello.py.
-
In the lower panel, select the TERMINAL tab.
-
Paste the following command in the Codespace's remote terminal to show the installed versions of several tools. Note the versions for comparison later.
node --version dotnet --version python --version gh --version
-
Paste the following command to run the Python program in the Codespace's remote terminal.
python src/hello.py
⌨️ Activity: Push changes to your repository from the codespace
-
Replace the
src/hello.pyfile contents with the following and save the file.print("Hello World!")
-
With the message updated, commit the change and push it to GitHub. Use VS Code's source control tools or the below terminal commands.
git add 'src/hello.py' git commit -m 'fix: incomplete hello message' git push
-
(optional) Back in your web browser, open the
src/hello.pyfile to to verify the change was updated. -
With the the change pushed to GitHub, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.
Step 1 - Passed ✅
Status Description ✅ - Pass Hello message fixed in hello.py 🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 2! One moment... 🤓Step 2: Use a custom image in your codespace
The didn't specify any configuration for the codespace we just created, so GitHub used a default Docker image. While this is very useful, it won't be consistent and it doesn't version lock our runtime environment. Specifying the configuration is important to keep the development environment repeatable.
Let's do that now by providing a specific docker container image.
How to configure a Codespace?
Configuration is provided directly in the repository via the
.devcontainer/devcontainer.json. You can even add multiple configurations!Let's create this file and set a few of the most common settings. For other options like setting configuring VS Code, forwarding ports, and running lifecycle scripts, see the Codespaces documentation on GitHub.
⌨️ Activity: Customize the codespace
-
Ensure you are in the VS Code Codespace.
-
Use the VS Code file explorer to create the configuration file.
.devcontainer/devcontainer.json
Alternately, run the below terminal command to create it.
mkdir -p .devcontainer touch .devcontainer/devcontainer.json
-
Open the
.devcontainer/devcontainer.jsonfile and add the following content. Let's start with a basic image.{ "name": "Basic Dev Environment", "image": "mcr.microsoft.com/devcontainers/base:debian" }💡 Tip: The name is optional but it will help identify the configuration when creating a codespace on GitHub, if there are multiple options.
-
After saving, VS Code likely popped up a notification that it detected a configuration change. You can Accept that option to rebuild the development container or manually use the Command Palette (
CTRL+Shift+P) and run the commandCodespaces: Rebuild Container. Select the Rebuild option. A full build is not necessary.
-
Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.
-
Expand the lower panel and select the TERMINAL tab.
-
Use the following command to check the tool versions again. Notice that none are installed now!
node --version dotnet --version python --version gh --version
-
⚠️ There is currently a bug with Codespaces that expects Git-LFS to be installed. Run the following command to remove the affected Git hooks.rm .git/hooks/post-checkout rm .git/hooks/post-commit rm .git/hooks/post-merge rm .git/hooks/pre-push
-
With our new configuration verified, let's commit the changes. Use VS Code's source control tools or the below terminal command.
git add '.devcontainer/devcontainer.json' git commit -m 'feat: Add codespace configuration' git push
-
With our dev container configuration committed, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.
-
Step 2 - Passed ✅
Status Description ✅ - Pass Devcontainer image set to base:debian 🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 3! One moment... 🤓Step 3: Add Features
You can further customize your codespace by adding container feature, VS Code extensions, VS Code settings, host requirements, and much more.
Let's add the GitHub CLI, extensions to run the python program using VS Code, and a custom script to install some packages when first creating the Codespace.
⌨️ Activity: Add support for the Python
-
In VS Code, open the Command Palette (
CTRL+SHIFT+P) and select the below command.Codespaces: Add Dev Container Configuration Files...
-
Select the option
Modify your active configuration.... -
In the list of features, search for and select
Pythonfromdevcontainers.- Instead of the defaults, pick
Configure Options. - Leave
Install Toolsset totrue. - Select Python version:
3.10
- Instead of the defaults, pick
-
Navigate to and open the
.devcontainer/devcontainer.jsonfile. -
Verify a new entry similar to the below was added.
"features": { "ghcr.io/devcontainers/features/python:1": { "installTools": true, "version": "3.10" } },
⌨️ Activity: Add VS Code extensions
-
In the left navigation, select the Extension tab.
-
Search for
pythonand find entries forPythonandPython Debugger.
-
Right click on each entry and select the
Add to devcontainer.jsonoption.
-
Navigate to and open the
.devcontainer/devcontainer.jsonfile. -
Verify a new entry similar to the below was added.
"customizations": { "vscode": { "extensions": [ "ms-python.python", "ms-python.debugpy" ] } },
⌨️ Activity: Add a custom script
The Dev Container specification provides multiple locations to run lifecycle scripts to further customize your Codespace. Let's add the
postCreateCommandwhich runs one time after initial build (or rebuild).-
Use the VS Code file explorer to create a script file with the below name.
.devcontainer/postCreate.sh
Alternately, run the below terminal command to create it.
touch .devcontainer/postCreate.sh
-
Make the script executable by running the below terminal command.
chmod +x .devcontainer/postCreate.sh
-
Open the
.devcontainer/postCreate.shfile and add the following code, which will install an animation of a steam locomotive.#!/bin/bash sudo apt-get update sudo apt-get install sl echo "export PATH=\$PATH:/usr/games" >> ~/.bashrc echo "export PATH=\$PATH:/usr/games" >> ~/.zshrc
-
Navigate to and open the
.devcontainer/devcontainer.jsonfile. -
Create the
postCreateCommandentry at the same level (top level) asfeatures, andcustomizations."postCreateCommand": ".devcontainer/postCreate.sh"
-
With our new configuration finished, let's commit the changes. Use VS Code's source control tools or the below terminal command.
git add '.devcontainer/devcontainer.json' git add '.devcontainer/postCreate.sh' git commit -m 'feat: Add features, extensions, and postCreate script' git push
-
Open the VS Code Command Palette (
CTRL+Shift+P) and run theCodespaces: Rebuild Containercommand. Select the Rebuild option. A full build is not necessary.
-
Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.
-
With the customizations committed, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.
Tip
You can also configure your account to install dotfiles, allowing you to combine personal configurations with the project's configuration.
⌨️ Activity: (optional) Verify our customizations
Now that you've rebuilt the codespace, let's verify the python extension, python version, and custom script were adjusted correctly in the Codespace.
-
Ensure you are in the Codespace.
-
In the left sidebar, click the extensions tab and verify that the Python extensions are installed and enabled.
-
In the left sidebar, select Run and Debug tab and then press the Start Debugging icon. VS Code will open the lower panel and show the run logs.
-
In the lower panel, switch to the TERMINAL tab.
-
Run the following command to show the installed version of Python. Notice the others are not installed.
node --version dotnet --version python --version gh --version
-
Run the following command to show the steam locomotive animation.
sl
-
Step 3 - Passed ✅
Status Description ✅ - Pass Features added to devcontainer.json ✅ - Pass Customizations added to devcontainer.json ✅ - Pass Postcreate command added to devcontainer.json ✅ - Pass Postcreate script created 🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 4! One moment... 🤓Step 4: Test out our Codespace
The final test of our Codespace is to put ourselves in the position of an onboarding developer. Let's close everything and start up a new Codespace from nothing.
⌨️ Activity: Delete the existing codespace
-
Close the window running your VS Code Codespace.
-
Navigate to your exercise repository.
-
Above the files list on the right, click the green <> Code button.
-
Select the Codespaces tab to show the list of created Codespaces.
-
Find the active entry, select the three dot menu
..., and select the Delete command.
Tip
You can manage all of your Codespaces across all projects at https://github.com/codespaces
⌨️ Activity: Start a codespace
-
Above the files list on the right, click the green <> Code button.
-
Select the Codespaces tab and click the plus sign
+or Create codespace on main button.Alternately you can select the three dot menu
...to choose a different machine type, location, or configuration. -
Wait a few minutes for the Codespace to be created and VS Code to connect.
-
(optional) Test out some of the activities from the previous steps to see if they still work!
-
Add an issue comment to let Mona know you finished this activity, then give her a moment to share the final review.
Hey @professortocat, I've finished testing out my new Codespace. I'm ready to review! -
Nice work! You are all done! 🎉
-
Please, follow the steps above.
I'll watch your progress in the background to provide feedback. 🧐Hey @professortocat, I've finished testing out my new Codespace.
I'm ready to review!Review
Here's a recap of all the tasks you've accomplished in your repository:
- You learned how to create a codespace and push code to your repository from the codespace.
- You learned how to use custom images, features, extensions, and scripts in your codespace.
- You learned how to test run it like an onboarding developer.
Additional learning and resources
- Developing in a codespace. Learn how to delete a codespace, open an existing codespace, connect to a private network, forward ports, and much more.
- Set up your repository. Learn how to set minimum machine specs for a codespace, add badges, set up a template repo, and much more.
- Personalize and customize GitHub Codespaces. Learn how to use setting sync for your codespace, add dotfiles, set the default region, set the default editor, and much more.
- Prebuild your codespace
- Manage your codespace
What's next?
- Take another GitHub Skill exercise.
- Read the Get started with GitHub docs.
- To find projects to contribute to, check out GitHub Explore.
Congratulations @briefjo! You finished the exercise! 🎉🎉🎉
We've updated the repository with a couple changes to highlight your success!
Return to the repository home page to see your progress!
Code with Codespaces
👋 Hey there @briefjo! Welcome to your Skills exercise!
Let's create a pre-configured environment to simplify development!
✨ This is an interactive, hands-on GitHub Skills exercise!
As you complete each step, I’ll leave updates in the comments:
Let’s get started - good luck and have fun!
— Mona