Github Codespaces

Background

GitHub Codespaces is a cloud-based development environment that allows you to work on your projects from anywhere. You can use it from any computer with a web browser.

Advantages of using Codespaces include:

  • No installation required: You don't need to install any software on your local machine.
  • Consistent environment: Your development environment is the same regardless of the device you use.
  • Work from anywhere: You can access your projects from any location with an internet connection.

This video has a brief overview and demonstration of Codespaces. Refer to the rest of this guide for more detailed instructions.

Key concepts

Git
Software for tracking changes to files. Industry standard for managing code projects. A Git repository is a project (folder) that is being tracked with Git.
Github
Web based service for storing Git repositories (projects).
Codespace
Cloud based virtual computer that can be used to edit or run code that is in a Github repository.

Set Up Github Account

To set up a Codespace you need to have a GitHub account. You should sign up for one using your Chemeketa email address (my.chemeketa.edu) to be eligible for increased Codespaces usage limits and other benefits.

Once you have set up your account, you can verify your student status via your profile in GitHub under Education Benefits.

You can start using Codespaces for free while your account is being verified. You will just have a lower limit on how many hours you can use it each month (120 hours instead of 180).

Create a Repository

A Codespace is created from a GitHub repository. There are three provided templates you can use to create a repository for your Codespace:

  • Basic Project Template - A C++ project with a main.cpp file.
  • Unit Test Template - A C++ project set up to run the doctest unit test framework.
  • Combo Template - A C++ project set up with two build targets: one for a main.cpp file and one for the doctest unit test framework.

If you don't have specific instructions from your instructor, you should use the basic template.

After selecting a template, follow these steps to create a repository:

  1. Find the green Use this template button on the repository page for one of the templates above. Click it and select Create a new repository. (Do NOT select "Open in Codespace" unless you do not care about saving your work.)
  2. Give your new repository a name (for example, "cs161-testing") and set it to be Private.
  3. Click the green Create repository button.

Create a Codespace

Once your repository is created, you can create a Codespace from it. Follow these steps:

  1. On the next page, click the green Code button and select the Codespaces tab.
  2. Click the Create Codespace on main button.
  3. Wait a few minutes for the Codespace to be created and started. (Opening a Codespace you have used recently will be much faster.)

The repository is a permanent place to store your code. The Codespace is a temporary environment for working on that code.

When you open a Codespace, it will have a copy of the code in the repository. But changes you make in the Codespace are not automatically saved to the repository. You will need to commit and push your changes to save them permanently. See the section below on Committing and Pushing Code for details.

Common Errors

If you get an error "Oh no, it looks like you are offline!", it means that your browser is blocking some of the resources. This is due to cookie or tracking protection settings in your browser. Try the following:

  • Disable any ad-blocking extensions you have installed.
  • In Firefox, click the shield icon to the left of the address bar and set "Enhanced Tracking Protection" to "Standard" or "Off". (Or go to settings and find Enhanced Tracking Protection and set it to one of those levels for all sites.)
  • In Chrome, click the lock icon to the left of the address bar and set "Site settings" -> "Cookies and site data" to "Allow all cookies".
  • In Edge, click the lock icon to the left of the address bar and set "Tracking prevention" to "Balanced" or "Basic". (Or go to settings and find Tracking Protection and set it to Balanced or Basic for all sites.)

Managing Codespaces

Codespaces are not free. You get a limited number of hours each month (120 or 180 depending on your account status). You can see how many hours you have used and how many you have left on your billing page. Storage used for codespaces also counts against your limits.

Codespaces that are not being used are automatically stopped after 30 minutes. But closing your browser does not stop the Codespace. You should manually stop your Codespace when you are done working in it to avoid using up your hours. You can stop a Codespace by opening the Command Palette (Ctrl-Shift-P or Cmd-Shift-P) and typing "Codespaces: Stop Current Codespace" and pressing Enter.

You can review your current Codespaces at the Codespaces page on GitHub. From there you can open, stop, or delete any of your Codespaces. Deleting a Codespace will delete any files you have created in it that have not been committed to git and pushed to GitHub. So before you delete a Codespace that has code you care about, you should either download the files or commit and push them to GitHub.

Periodically review your Codespaces and delete any you are no longer using to avoid the storage counting against your limits.

You generally should only have the most recent assignment or two in Codespaces. After you are done with them, sync the changes back to your repository (or download the files) and delete the Codespace.

You also will likely want a "testing" codespace or two. But try to reuse those rather than creating new ones each time you want to test out a code sample.

Key Concepts

Running Codespace
A Codespace that is running is using your hours. You can use it to edit and run code.
Stopping a Codespace
Puts the virtual machine to sleep. The code in the Codespace is not deleted, but the Codespace is not running and not using any of your hours. To use the codespace again, you need to open it and start it.
Deleting a Codespace
Permanently deletes the virtual machine and all files in it that have not been committed to git and pushed to GitHub. You cannot recover a deleted Codespace.

Downloading Files

To download files from your Codespace to your local computer, you can use the file explorer in the left sidebar of VS Code. Right-click on the file you want to download and select Download.

To download the entire folder (for submitting an assignment) you will first want to make a .zip file (compressed file that contains all the files and folders) of the entire project. Open the command palette (Ctrl-Shift-P or Cmd-Shift-P) and type "zip" and select Zip Project. This will create a file called project.zip in the root of your project. You can then right-click on that file in the file explorer and select Download.

If you do not see "Zip Project" in the command palette, you can install it manually:

  • Press Ctrl-Shift-X or Cmd-Shift-X to open the Extensions view.
  • Search for "Zip Project", look for the extension named "Kaiser's Project Zip",and click the Install button.

Other than to turn in work, or to save a local backup, you likely do not want to download your project. Once you download the code, it will be disconnected from the repository.

To "save" your work permanently, you should commit and push your changes to the repository your Codespace was created from. See the next section

If you want to work locally on a project you have set up in a Codespace, first sync your changes to the repository. (See the the next section.) Then you can clone the repository to your local machine and work on it there. See the Local Development Guide for instructions on how to do that.

Committing and Pushing Code

If you want to permanently save your code in GitHub so that destroying the Codespace will not delete it, you need to commit and push your code to GitHub.

To do so, open the Source Control view by clicking on the Source Control icon in the left sidebar (it looks like a branch with a dot on it).

If the button Commit is enabled, you can enter a commit message and click it to commit your changes. (If you have been using the Chemeketa templates, it is likely your changes are already commited).

Once your changes are committed, you should see a button Sync Changes. Click it to push your changes to your permanent repository on GitHub.