Getting started with Codespaces

What is Codespaces?

GitHub Codespaces (Codespaces) is an online service from GitHub that allows you to edit files and run computer programs via a web browser. The files and computer programs are hosted on and run from a remote server run by GitHub.

For FreeSewing, you can use Codespaces to edit our repository files to modify existing designs, add new files to create new designs, and run the FreeSewing lab website so you can test designs. You can also edit, add, and test documentation files in Codespaces. Because all of this is is done online via a web browser, you do not need to have or use your own computer to perform this development work.

Accessing Codespaces

Access Codespaces from the GitHub website while logged in:

• The “Your Codespaces” page is accessed via the “Codespaces” link at the top of any GitHub page.
• A shortcut URL is: https://github.com/codespaces

Creating a codespace

To create a new codespace:

• Select the “New codespace” button at the top of the Your Codespaces page.
• A shortcut URL is: https://github.com/codespaces/new

This will open a “Create a New Codespace” page.

On the Create a New Codespace page, select the options for your codespace:

• Repository -> (“username/freesewing” assuming that is the name of your GitHub repository)
• Branch -> (select the branch you want to use)
• Region -> (select the region most appropriate for you)
• Machine type -> (choose “2-core”)
• Press the “Create codespace” button.

The Codespaces app will open in the browser window. The Codespaces app is basically the Visual Studio Code app with Codespaces and GitHub integration built in.

(Wait 45 seconds or so for the Codespace app to clone the repository from GitHub to the codespace repository and start.)

Editing files

You can browse and edit files in your codespace repository from within the app:

• On the Activity Bar on the far left side of the page, select the Explorer icon. (The icon looks like two pages of paper.)
• Use the Explorer sidebar to browse your repository and select a file to edit.
• Edit the file in the main window of the app.

Saving, committing, and pushing changes

Auto-save is enabled by default, so any changes you make are automatically saved in your codespace repository.

To commit changes to your codespace repository:

• In the Activity Bar on the far left side of the page, select the Source Control icon.
• In the Source Control sidebar you can see a list of changed files.
• Press the ”+” plus icon next to a file to stage it in preparation to commit.
• Type a commit message in the text box and press the “Commit” button. This commits the staged files to your codespace repository.

To push committed changes from your codespace repository back to your GitHub repository:

• After committing changes to your codespace repository, press the “Sync Changes” button to push the committed changes to your GitHub repository.
• There is also an ”…” ellipses menu at the top of the Source Control sidebar that you can use. Select the “Push” menu item.

Running the lab, dev, and org websites

In the “Terminal” panel at the bottom of the page, you can run commands.

To start the lab website (to view and test new designs and design changes):

• In the Terminal panel, run yarn kickstart and then yarn lab.

To start the dev or org websites (to view and test documentation changes):

• dev: In the Terminal panel, run cd sites/dev and yarn start.
• org: In the Terminal panel, run cd sites/org and yarn start.

After the lab, dev, or org website starts:

• The usual localhost:8000 port will automatically be forwarded to a custom URL.
• A pop-up will appear saying that the port has been forwarded. The “Open in browser” button on the pop-up will open a new browser tab/window with the custom URL.
• You can also access the custom URL via the “Ports” panel.

To make a website publicly available

Forwarded ports are private by default. The custom URL page is accessible only to you, the GitHub user who owns the codespace, while you are logged into your GitHub account. However, you can make the port public so others can access it (or so you can access it on a different browser while not logged into GitHub).

To make the port public:

• In the Ports panel, right-click on the port and select Port Visibility -> Public.
• The custom URL will be now be a publicly-accessible forwarded port. You can copy and share the custom URL.

Starting and stopping a codespace

You can start and stop your codespace via the Your Codespaces page.

• To start: Click on the codespace name to browse to the Codespaces app URL for that codespace. (You can also right-click to copy the URL and open it in a different browser window.)
• To stop: Open the ”…” ellipses menu next to the codespace and select “Stop codespace”.

Renaming a codespace

Each new codespace is generated with a random name. You can rename a codespace to make it easier to identify. (This will help if you have more than one codespace.)

To rename a codespace:

• Go to the Your Codespaces page.
• Open the ”…” ellipses menu next to the codespace and select “Rename”.

Codespaces settings

You can access GitHub Settings via the user icon menu in the upper right corner of any GitHub page (but not on the Codespaces app page).

• Selecting the “Settings” menu item will open the GitHub Settings page.
• The Codespaces settings are under “Codespaces” in the left sidebar on the Settings page.
• A shortcut URL is: https://github.com/settings/codespaces

Among the Codespaces settings available are:

• “Default idle timeout” (how long codespaces continue to run when idle, before being stopped)
• “Default retention period” (how long codespace repositories are kept when unused, before being deleted)

Usage and Quotas

To check usage:

• Usage information is under “Billing and plans” in the left sidebar on the Settings page.
• A shortcut URL is: https://github.com/settings/billing

About quotas:

• As a free account user, you have a quota of 120 core-hours of usage and 15 GB of storage per billing month. That is the total for all your codespaces combined.
• However, because your codespace uses a 2-core machine, you effectively have only 60 hours of usage per month.
• (You can also select a 4-core machine for your codespace, but that would reduce the effective usage quota to only 30 hours per month.)
• You will receive email notifications and and toast messages in the Codespaces app when you have used 75%, 90%, and 100% of your quotas.
• Quotas reset each month at the start of your account’s billing cycle. (Billing cycle start/end dates are different for each user.)

Deleting a codespace

To delete a codespace:

• Go to the Your Codespaces page.
• Open the ”…” ellipses menu next to the codespace and select “Delete”.