Exercise: Code with Codespaces

[github-actions]

Code with Codespaces

👋 Hey there @bakiroo! Welcome to your Skills exercise!

Let's create a pre-configured environment to simplify development!

As you complete each step, I will respond in the comments to:

• check your work and give feedback
• share next steps
• occasionally share tips
• congratulate you when you finish!

Good luck and have fun!
- Mona

[github-actions]

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

1. Open a second tab and navigate to this repository. Ensure you are on the Code tab.

2. Above the files list on the right, click the green <> Code button.

   

3. 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.

4. 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

1. Ensure you are in the VS Code Codespace.

2. In the left sidebar, select the file Explorer tab and open the file src/hello.py.

   

3. In the lower panel, select the TERMINAL tab.

   

4. 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

5. 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

1. Replace the src/hello.py file contents with the following and save the file.

   print("Hello World!")

2. 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

3. (optional) Back in your web browser, open the src/hello.py file to to verify the change was updated.

4. 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.

[github-actions]

Step 1 - Passed ✅

Status	Description
✅ - Pass	Hello message fixed in hello.py

[github-actions]

🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 2! One moment... 🤓

[github-actions]

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

1. Ensure you are in the VS Code Codespace.

2. 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

3. Open the .devcontainer/devcontainer.json file and add the following content. Let's start with a basic image.

   {
     "name": "Basic Dev Environment",
     "image": "mcr.microsoft.com/vscode/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.

4. 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 command Codespaces: Rebuild Container. Select the Rebuild option. A full build is not necessary.

   

5. Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.

6. Expand the lower panel and select the TERMINAL tab.

7. Use the following command to check the tool versions again. Notice that none are installed now!

   node --version
   dotnet --version
   python --version
   gh --version

8. ⚠️ 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

9. 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

10. With our dev container configuration committed, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.

[github-actions]

Step 2 - Passed ✅

Status	Description
✅ - Pass	Devcontainer image set to base:debian

[github-actions]

🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 3! One moment... 🤓

[github-actions]

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

1. In VS Code, open the Command Palette (CTRL+SHIFT+P) and select the below command.

   Codespaces: Add Dev Container Configuration Files...

   

2. Select the option Modify your active configuration....

3. In the list of features, search for and select Python from devcontainers.

   • Instead of the defaults, pick Configure Options.
   • Leave Install Tools set to true.
   • Select Python version: 3.10

4. Navigate to and open the .devcontainer/devcontainer.json file.

5. 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

1. In the left navigation, select the Extension tab.

   

2. Search for python and find entries for Python and Python Debugger.

   

3. Right click on each entry and select the Add to devcontainer.json option.

   

4. Navigate to and open the .devcontainer/devcontainer.json file.

5. 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 postCreateCommand which runs one time after initial build (or rebuild).

1. 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

2. Make the script executable by running the below terminal command.

   chmod +x .devcontainer/postCreate.sh

3. Open the .devcontainer/postCreate.sh file 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

4. Navigate to and open the .devcontainer/devcontainer.json file.

5. Create the postCreateCommand entry at the same level (top level) as features, and customizations.

   "postCreateCommand": ".devcontainer/postCreate.sh"

6. 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

7. Open the VS Code Command Palette (CTRL+Shift+P) and run the Codespaces: Rebuild Container command. Select the Rebuild option. A full build is not necessary.

   

8. Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.

9. 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.

1. Ensure you are in the Codespace.

2. In the left sidebar, click the extensions tab and verify that the Python extensions are installed and enabled.

   

3. 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.

   

4. In the lower panel, switch to the TERMINAL tab.

5. 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

6. Run the following command to show the steam locomotive animation.

   sl

[github-actions]

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

[github-actions]

🎉🎉🎉 Nice work! Everything is perfect! 🎉🎉🎉
Preparing content for step 4! One moment... 🤓

[github-actions]

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

1. Close the window running your VS Code Codespace.

2. Navigate to your exercise repository.

3. Above the files list on the right, click the green <> Code button.

4. Select the Codespaces tab to show the list of created Codespaces.

   

5. 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

1. Above the files list on the right, click the green <> Code button.

2. 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.

3. Wait a few minutes for the Codespace to be created and VS Code to connect.

4. (optional) Test out some of the activities from the previous steps to see if they still work!

5. 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!

6. Nice work! You are all done! 🎉

[github-actions]

Please, follow the steps above.
I'll watch your progress in the background to provide feedback. 🧐

[bakiroo]

Hey @professortocat, I've finished testing out my new Codespace.
I'm ready to review!