While the quick GitHub.dev interface is great for quick edits, many projects require the ability to run applications and execute code as you would on your personal computer. Fortunately, GitHub offers a service to run such programs on their servers.
. Each codespace is essentially a personal virtual computer that runs in the cloud, that you access through your web browser.
Full documentation on Codespaces is available on docs.github.com 2
docs.github.com/en/codespaces
.
Note4.1.2.
To create a Codespace on any repository you own, use the green “Code” button, select the Codespaces tab, and press the green “Create codespace on [branchname]” button.
After the Codespace boots up, you’ll have an interface similar to the GitHub.dev environment you learned about in Section 2.4.
Note4.1.3.
Here are a few key differences between GitHub.dev and Codespaces.
A GitHub.dev URL looks like github.dev/username/reponame, while a Codespace URL looks like random-word-123randomcharacters789.github.dev.
GitHub.dev is quicker to load than a Codespace.
GitHub.dev has a much more limited selection of VS Code extensions to use.
You can only install applications and execute code on a Codespace.
One similarity between GitHub.dev and Codespaces (besides the obviously similar VS Code user interfaces), is that your work is still private to you and can only be shared with the public (and retained in the long term) by committing and pushing your progress every so often to your GitHub.com repository. The Source Control tool works slightly different in a Codespace, however.
Note4.1.4.
One quick way to commit and push your changes from a Codespace is to use “Source Control” from the left toolbar.
Enter a short commit message describing your changes as a note to yourself. (This is required and can be a pain to fix if you forget to do so!)
Select “Commit & Sync” from the menu next to the green Commit button.
In the dialogs that follow, I suggest choosing to “Always” stage all your changes and commit them directly, then “OK, Don’t Show Again” when told this action will pull and push commits from and to origin/main, and finally “Yes” that you would like your Codespace to periodically run git fetch.
Section4.2Writing and Running Code
Now that we’ve provisioned our Codespace virtual cloud computer, we can use it to write and execute code using our web browser for essentially any programming lanugage.
Our first example will be Python, a popular general-purpose programming language (and the same language we will use in Chapter 6 for Jupyter notebooks). In your Codespace, right-click on the file Explorer to create a “New File...”. Name this file something.py so your Codespace recognizes the file as a Python script (due to the .py file extension). This should trigger the prompt shown in Figure 4.2.1 to install a Python extension - go ahead and do it.
Add the line print("Hello world!") to your file. A “play” icon (▶) should be displayed in the upper-right corner of the text editor (thanks to the Python extension you installed). Clicking this button should execute the code to print a greeting as in Figure 4.2.2.
Unless your Codespace has been customized via a .devcontainer.json file (which we won’t get into here), you’ll be using the default Codespace image provided by GitHub. This environment is ready to execute code from various standard programming lanugages, though for some of them you may need to run the script using the Terminal.
Definition4.2.3.
A terminal is a command-line prompt used to run programs that don’t have a graphical user interface. Type the command and hit Enter to run it.
Remark4.2.4.
To open a terminal on demand in a Codespace, use the shortcut Ctrl/Cmd+Shift+`.
What do you think the programs in Listing 4.2.5, Listing 4.2.6, and Listing 4.2.7 will output? Copy-paste them into a file in your Codespace, then run to find out!
Section4.3Previewing GitHub Pages
Another useful application of Codespaces is the ability to preview your GitHub Pages site created in Section 3.2. Return to that repository on GitHub.com and create a new Codespace (Note 4.1.2).
To spin up your live preview, open a terminal by using the shortcut noted in Remark 4.2.4. To make sure the necessary software has been installed, type bundle and hit Enter. Then, you can enter jekyll serve to start the preview server.
You’ll see some output, and eventually Server address: http://127.0.0.1:4000. At that time an alert will appear that says “Your application on port 4000 is available”. You can use its “Open in browser” button, or hover over the http://127.0.0.1:4000 link to be given the same option.
This should open a URL such as random-words-123randomletters789-4000.app.github.dev, which will show a live preview of your GitHub Pages site in a new tab. As soon as you make edits in your Codespace tab, you can return to this tab to (within a second or two) see how your edits will update your live site. Note that this URL is private to you, and your public site won’t be updated until you Commit & Sync your changes (Note 4.1.4).
Personally, I use GitHub.dev (or even just the GitHub.com edit button) rather than a full Codespace when adding a quick post or making a quick edit on many of my GitHub Pages websites. But the Codespace option is very handy for when bigger changes are necessary, and you want to make sure everything looks just right before pushing it live to the public.
Section4.4Managing Your Codespaces
GitHub users are provided with a limited amount of free Codespace hours and storage each month, with additional resources available to Pro users, including those with the free GitHub Education benefit (Note 2.1.2). If needed, there is the option to pay for additional resources.
As a mathematician who almost exclusively uses GitHub Codespaces for doing the kinds of work described in this handbook (and does so for much longer periods of time than a tpyical mathematician), I’ve only surpassed GitHub’s free quota on the rare occassion (and when I do, I’ve paid only \$2-\$6 per month). I accomplish this by halting my Codespaces when I’m not actively working on them.
Note4.4.1.
To manage your Codespace resources, visit https://github.com/codespaces. You can stop a Codespace temporarily to preserve your hourly quota, and delete a Codespace you don’t plan to use for a while to save on your storage quota. While actively working in a Codespace, you can stop it by pressing Ctrl/Cmd+Shift+P, typing stop current codespace, and confirming.
In any case, a stopped Codespace can be restarted later when you want to resume work, even if you haven’t committed and pushed your changes. (But be warned: a stopped Codespace and its uncommitted changes may be deleted by GitHub after a few days of inactivity, so don’t leave it alone for long.)
A deleted Codespace can always be recreated later based upon your most recent commit.
Putting it all together, we have seen three ways to access files on your repo. Going from the least easy to edit to the most editable we have: GitHub.com, GitHub.dev, random-codespace-string.github.dev. Here is what these environments look like.
Section4.5Powering up your Codespce
By default, your codespace will use a 2-core processor, 8GB of RAM, and 32GB of storage, with a quota of 40 usage hours per month. This is fine for many tasks, but if you’re doing data analysis (Chapter 6) or formalized mathematics (Section 7.3) you may want some more resources at your disposal.
Remark4.5.1.
You can double (or quadruple, or \(8\times\text{,}\) etc.) your resources by “changing the machine type”. There are several ways to accomplish this, via https://github.com/codespaces/, or by typing “Change Machine Type” in the Codespace command pallette (accessed via Ctrl/Cmd+Shift+P).
Note however, that if you double your resources, you are also doubling your usage time (e.g. running a 4-core machine uses one hour of your quota every 30 minutes).
Section4.6Custom Codespaces
A key feature of Codespaces is that they can be customized by the use of a .devcontainer.json file (or .devcontainer directory). Such files describe the virtual machine that should be provisioned when creating a Codespace, allowing for the automatic installation of appropriate software/libraries/dependencies necessary for the use of a given repository.