Skip to content

Running OpenSAFELY in GitHub Codespaces

Warning

GitHub Codespaces support is still being tested. This documentation is subject to change.

The OpenSAFELY research template contains a configuration to allow you to run OpenSAFELY without any installation required on your own computer.

This uses GitHub Codespaces.

What is GitHub Codespaces?🔗

Codespaces is a coding environment hosted online by GitHub. Codespaces can be accessed via your web browser without any additional installation.

A codespace provides:

  • a "virtual machine" — a computer running as software inside another computer — that is hosted by GitHub
  • a Visual Studio Code environment for editing your project and running commands

When you open a codespace in browser, you get access to the Visual Studio Code environment. Through that interface, you can run commands inside the codespace's virtual machine. This is just as if it were a real desktop or laptop that you were working on, but does not require any installation.

This removes the need to have anything other than a web browser installed to work on OpenSAFELY projects.

Create a GitHub account🔗

Before starting with OpenSAFELY in GitHub Codespaces, you will need a free GitHub account:

  1. Create a free GitHub account, if you do not already have one.
  2. Login to that GitHub account.

Working on OpenSAFELY projects via GitHub Codespaces🔗

To start a Codespace, you need to create a code repository that you can launch a codespace from.

We will use the OpenSAFELY research template as a basis for our code.

Create a code repository for your work🔗

You only need to create a code repository once for a particular project:

  1. Create a new research code repository under your own username based on the research template.

Warning

This step will enable you to work on your code in Codespaces, and check that it would work with OpenSAFELY.

It will not allow you to run code on OpenSAFELY's platform.

For that, you would have to request that your repository is transferred to the opensafely organization. Existing OpenSAFELY users typically create a repository within the opensafely organization.

Launch a codespace🔗

Once you have a code repository created, you can launch a codespace from that repository:

  1. Navigate to the newly created research repository.
  2. Click the "Code" button 1.

When this finishes launching, you should see a Visual Studio Code editor with three panes:

  • on the left, the file explorer
  • a terminal at the bottom-right
  • a file editor at the upper-right

Editing code🔗

The file explorer shows the contents of your code repository. You can open files by double-clicking them.

Updating files in the repository🔗

This is a two-step process.

  1. Save a file in Visual Studio Code. This only saves the file locally inside the Codespace. These changes will not yet show up in your GitHub code repository.
  2. Use the Source Control view to add, commit and publish those changes to your GitHub repository. If you are unfamiliar with Visual Studio Code and GitHub, GitHub has a guide on using this.

A quick guide to OpenSAFELY features🔗

Now that we have a GitHub codespace running, we can use OpenSAFELY.

Here is a short and non-exhaustive guide to how things work.

Running the OpenSAFELY CLI🔗

  • You can run the OpenSAFELY CLI in GitHub Codespaces. In the Visual Studio Code terminal, type opensafely and press ++Enter++.

  • See the OpenSAFELY CLI documentation for more.

🔗

GitHub Codespaces computer resources🔗

The default codespace has 2 computer processor cores (CPU cores) and 4 GB memory (RAM). In some cases, you may find that OpenSAFELY projects exceed the available RAM.

GitHub Codespaces does have virtual machines with more CPU cores and RAM, but these will use the free quota more quickly.

It is possible to configure what virtual machine type the codespace has when launching the codespace. See GitHub's explanation of configuring advanced options for a codespace.

It is also possible to change a virtual machine type for an existing codespace.

GitHub Codespaces billing🔗

GitHub gives all users a free and decent-sized monthly quota for Codespaces. This is accessible without a paid account. See GitHub's pricing details.

Note

You will not get billed for using Codespaces, unless you both:

  • set a Codespaces spending limit
  • and add a payment method

Without billing configured, if you run out of free quota, GitHub will only block you from using Codespaces until the next monthly cycle starts.

Managing codespaces🔗

If you close a codespace in your browser, it still continues running. You can return to an open codespace from the code repository.

It is useful to stop or delete codespaces to prevent them from using your quota unnecessarily.

Stopping a codespace🔗

See GitHub's documentation for how to stop a codespace.

This stops a codespace running, but allows you to restart it.

Stopped codespaces still incur storage usage.

Deleting a codespace🔗

See GitHub's documentation for how to delete a codespace.

Unlike stopping a codespace, this removes the codespace entirely,

Once deleted,

Idle timeout🔗

A codespace will eventually stop when it is not being used.. This is a useful feature to prevent you from wasting free or paid Codespaces credit. This setting can be configured to give a longer or shorter duration. See the GitHub documentation.

Info

We are still investigating how we can make Codespaces more useful for researchers working on OpenSAFELY projects.

Please feel free to ask us questions, tell us about problems you find, or give us any other feedback.