Skip to content

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.

This page:

  • explains what GitHub Codespaces is
  • explains how to run some OpenSAFELY features in GitHub Codespaces
  • briefly explains some features of GitHub Codespaces and directs the reader to GitHub's documentation for more details

You only require a web browser to follow the instructions in this page.

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.

Info

A codespace refers specifically to such a virtual machine environment, that contains a copy of your code to work on.

This is not to be confused with a "code repository" which is where code gets published on GitHub.

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 OpenSAFELY research 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.

When you update files by publishing to the repository's main branch, this should trigger an automated check of whether your code will run in OpenSAFELY. These checks can be viewed from the Actions tab, accessed via your repository on GitHub's You should be able to see an automated check running on the new version of your code.

Info

If you are comfortable with Git, you can also create and switch between different branches in the codespace,

A quick overview of what is included in the codespace🔗

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++.
  • You should see the OpenSAFELY CLI help prompt.
  • See the OpenSAFELY CLI documentation for more.

Running the example cohort-extractor project🔗

  • In the Visual Studio Code terminal, type opensafely run run_all and then press ++Enter++ to run the existing project.

Following the ehrQL tutorial🔗

Warning

The default research template repository still uses the older cohort-extractor. This makes getting started with ehrQL require some extra steps.

This process will be improved in future.

You will need to download the ehrQL example data by the following process:

  1. Ensure you are in the repository's top-level by changing directory to it with cd ~
  2. Create a new tutorial directory with: mkdir learning-ehrql
  3. Download files: wget …
  4. Unzip files: unzip …
  5. You should see the files.
  6. You can now remove the zipped file: rm …
  7. Change into the tutorial directory with cd learning-ehrql

With that done, you can proceed to "Running ehrQL". It may be useful to read the tutorial "Installation and setup" page, but everything else will then be ready for you.

Other features for development🔗

Running Jupyterlab🔗

  • In the Visual Studio Code terminal, type opensafely jupyter and then press ++Enter++ to launch the Jupyterlab server.
  • Your web browser should open a new tab or window or prompt you if you want to open a new tab or window. This new tab or window allows you to use the Jupyterlab server.
  • If this tab or window does not display, you can navigate to the Ports tab in the terminal, which will show the web address to the running server. Click on that link to access the Jupyterlab server.
  • You can edit and save files in your codespace from within Jupyterlab.

!!! warning

  You will still need to use Visual Studio Code to publish those changes made in your codespace,
  to your code repository
  [as detailed above](#updating-files-in-the-repository).

Running command-line Python🔗

  • In the Visual Studio Code terminal, type opensafely exec python and then press ++Enter++ to start command-line Python.

Running command-line R🔗

  • In the Visual Studio Code terminal, type opensafely exec r and then press ++Enter++ to start command-line R.

Info

We may look into providing a better experience for developing R code in future.

Running command-line Stata🔗

Info

This has not yet been tested, but could be added in future.

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, but not CPU 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, the codespace will not incur any usage

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.