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.

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 Codespace

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 Codespace:

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.
4. On the next page, click the green Code button and select the Codespaces tab.
5. Click the Create Codespace on main button.
6. Wait a few minutes for the Codespace to be created and started. (Opening a Codespace you have used recently will be much faster.)

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.

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.

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.

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.

Opening Codespaces on Your Computer

If you install Visual Studio Code, you can open a Codespace using it. Doing so may make it easier to apply your personal settings to the editor.

When doing so, the Codespace and all of your code is still running on a remote virtual machine, you are just interacting with that machine using your own copy of VSCode instead of the web based version of VSCode on the github website.

To open a Codespace on your computer:

1. Install Visual Studio Code on your computer.
2. Install the GitHub Codespaces extension in VSCode.
3. In VSCode, open the Command Palette (Ctrl-Shift-P or Cmd-Shift-P) and type "Codespaces: Connect to Codespace" and press Enter.
4. Select the Codespace you want to connect to.