What is GitHub Codespaces?
GitHub Codespaces allows you to create a virtual machine attached to a github-hosted repository.
This means you can:
-
Develop code in a web-based IDE (VSCode or Jupyter)
-
Debug, test and run an application with dedicated compute resources.
-
Access compute resources on-demand when working in the remote repository from VSCode desktop, with the Codespaces extension.
Notes on Billing and Usage:
Unused Codespaces: Codespaces on github.com are billed by core-hour, so these virtual machines will remain online while they are being used and will time-out and power off when not in use. You will receive an email notifying you when unused Codespaces will be deleted.
Codespaces Ownership: Accounts associated with the enterprise individually get a healthy allocation of compute resources through github for education that can be used for creating Codespaces on repos that you, as an individual, own. If your organization or department needs Codespace resources for repositories owned by that GitHub organization, the organization owner will need to enable Codespaces as an organization setting.
Codespaces are attached to the repository (or cloned repository) and use is billed to the repository owner or organization owner.
Getting Started with GitHub
Please start here before setting anything up: Getting Started with GitHub
Using GitHub Codespaces with GitHub Classroom:
Codespaces can be used with GitHub Classroom, with educators receiving a free allowance, estimated to be enough for a class of 50 with 5 assignments per month, on a 2 core machine with 1 Codespace stored per student.
GitHub Codespaces with Classroom Documentation: https://docs.github.com/en/education/manage-coursework-with-github-classroom/integrate-github-classroom-with-an-ide/using-github-codespaces-with-github-classroom
Using Codespaces
Once you have initialized a repository and uploaded a file, you can click the +code button on the github.com page for the repository to start a new Codespace.
You can choose what web IDE to load or access the resources of the Codespace while working on the remote repository through your local VScode install — just follow the link to open the Codespace in VScode and install the extension if needed.
Setting up a development environment in a Codespace
Using Codespaces for shared compute resources should include a bit of initial configuration of the environment including reviewing relevant configuration files in your repository to allow those cloning your repository to develop in a similar environment without deciphering which dependencies need to be installed.
This can include
1. Recording the steps used to get the environment up-and-running
2. Including these configuration settings in a .devcontainer/image.json , dockerfile or a docker-compose.yml within the repository with your base code
3. Utilizing a script for configuring your .venv or similar specific environments as required
4. Incorporating source resources (external databases) either within the repository or as web- accessible links.
If it is critical that students or collaborators work in a similar development environment, consider choosing a pre-built image, making any necessary changes, and including the relevant files with your base code.
Your Codespace is on-demand. Depending on how you use the git workflow and your repository set-up, it will probably only be accessible to you. Commit and include anything you need to distribute to run your project, or expect others to know to build their own environment.
DevContainers
If your project will rely heavily on development within Codespaces, please read the following comprehensive documentation from github:
https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers
https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds
If you are familiar with the devcontainer extension in VScode, Github’s devcontainers work similarly, with github hosted docker containers providing the compute resources rather than requiring the containers deployed on your local machine.
We recommend choosing a standard environment as a starting point:
Check out options for environments here; the default environment is sparse for most projects unless gathering dependencies and building the environment is part of the assignment:
Ready-to-go official templates for Codespaces. Popular forks of these may include extra dependencies and standard libraries. Review guidance before deploying or including in your repo:
https://github.com/orgs/github/repositories?language=&q=%22codespaces-%22&sort=&type=all
Pre-configured full devcontainer images, initially from Microsoft (now community maintained)
https://github.com/devcontainers/images/tree/main/src
DevContainer templates, initially from Microsoft (now community maintained)
https://github.com/devcontainers/templates/tree/main/src
The original Microsoft-configured DevContainers
https://github.com/microsoft/vscode-dev-containers
If your project requires a particular environment, we recommend reviewing what is installed in the .devcontainer directory of these images.
If your repository contains a .devcontainer directory, new Codespaces will draw from these configuration files in their initial setup. Review the guides from github:
https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers
https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds
Assignments & Submissions
When creating assignments on classroom.github.com, source repositories are owned by an organization. As an organization member who manages a classroom, you may find your organization needs to enable Codespaces organization-wide to use them on owned repositories. Contact your github organization owner as they can make this change for you.
When assigning to students via github classroom, students accepting the assignment clone a repository you build containing the base code (usually just instructions about the assignment, and a generated README that includes a submission link.) When students complete this assignment, they will:
1. Clone the base repository
2. Contribute their own changes
3. Submit via the submission link which will generate a pull request
Once students clone the repository, they will own the repository containing their submission and should be able to initialize their own Codespaces to work on the project as-needed. This is why it is important to include in the instructions for the project or in the repository itself any stipulations about the environment, dependencies, or allowed libraries that should or should not be included in the submission.
If changes to the environment are required for the submission to run, consider specifying how those configuration changes should be reflected as changes committed to the submitted repo, as students may find their project running in the environment they customized with additional dependencies but may neglect to include these changes as files with their submission, resulting in the project not running out-of-the-box for graders.
Synchronous Collaboration & Migrating from Google Colab
If you plan to migrate projects from Google Colab to make use of the compute resources of github Codespaces, be aware of the following:
1. The differences in the base development environment
Google Colab release notes https://colab.research.google.com/notebooks/relnotes.ipynb
GitHub Codespace base images:
https://github.com/devcontainers/images/tree/main/src/universal
Settings for the default image, for GitHub organization owners
https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/restricting-the-base-image-for-codespaces
2. The differences in workflow for collaboration between Jupyter Notebooks in Google Colab and Codespaces, which are specific to repository owners.
To enable collaborative work in Codespaces similar to Google Colab please:
1. Be familiar with the git workflow for version control and the motivations for this workflow, and how it differs from running jupyter notebooks natively or in google colab with tracked changes and synchronous editing.
2. Always commit changes as they are made when working in real-time with others
*3. It is easiest, to get repository permissions correct for editing by,
a. assigning a group project in github classroom, or
b. already be working in a team on github.com with the same permissions (write or maintain) for all contributors.
GitHub’s default synchronous collaboration tool for Codespaces is via the live-share VSCode plugin.
See documentation from github here:
https://docs.github.com/en/codespaces/developing-in-a-codespace/working-collaboratively-in-a-codespace
and from Microsoft, here:
https://learn.microsoft.com/en-us/visualstudio/liveshare/use/share-server-visual-studio-code
If you are used to working with live, collaborative Jupyter Notebooks, for instance, it is best to use the Jupyter template for Codespaces so you have a devcontainer with a full jupyter-lab install; start a notebook, forward the port, and share the server.
https://learn.microsoft.com/en-us/visualstudio/liveshare/use/share-server-visual-studio-code#share-a-server