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. GitHub provide users with a free monthly quota of Codespaces use.

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, except this virtual machines has been configured for OpenSAFELY use.

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. If you do not already have a GitHub account, go to the GitHub pricing page, and choose to sign up with a free account.
  2. Follow the process on GitHub's site.

Login to GitHub🔗

Whether you have created a new GitHub account, or are using an existing GitHub account, make sure that you are logged in to your 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.

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

  1. In your web browser, go to the research code template repository.
  2. Follow GitHub's instructions for creating a new repository from a template.

Info

To give more details about the choices given when creating a new repository from a template:

  • You can enter any name and description that you choose for your repository.
  • For this example, it does not matter whether the repository visibility is public or private. If you want others to see it, then you can make it public.
  • You do not need to select "Include all branches".
  • You can ignore the mention of "GitHub Apps from GitHub Marketplace" in GitHub's instructions.

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 research code repository created, you can launch a codespace from that repository:

  1. In a web browser, go to your newly created research code repository on GitHub.
  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🔗

A codespace is self-contained with its own copy of your repository's files. This is just as if you were working on a local copy of the repository on your own computer.

Changes to the copy of your repository in the codespace do not automatically change the state of your published repository on GitHub.

To get changes from a codespace to the GitHub repository, there 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, non-exhaustive guide to what OpenSAFELY provides in the codespace.

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 options.

Running the example project🔗

  • The research code repository that you created already has an OpenSAFELY project in it.
  • Ensure that the terminal is in the /workspaces/YOUR_REPOSITORY_NAME directory either:
  • by opening a new terminal window which defaults to this directory
  • or, by typing cd /workspaces/YOUR_REPOSITORY_NAME in an existing terminal and then pressing ++Enter++ TODO: explain how.
  • In the Visual Studio Code terminal, type opensafely run run_all and then press ++Enter++ to run the existing project.
  • This may take a few moments to download the required Docker images, before the project is run.

You should see:

=> generate_study_population
Completed successfully

Info

The research code example project is currently based on a legacy cohort-extractor project. In future, we will amend this to work with ehrQL directly.

ehrQL is replacing cohort-extractor.

  • In file explorer … TODO
  • In the terminal … TODO

Following the ehrQL tutorial🔗

Info

This process will be simplified considerably in future.

When creating the learning-ehrql directory, you can either:

  • TODO: Go to explorer outside of a directory; right click, "New folder", then open a new terminal in that directory.
  • TODO: Or, in the terminal, ensure that the terminal is in the /workspaces/YOUR_REPOSITORY_NAME directory

Create the learning-ehrql directory by:

mkdir learning-ehrql

This should be at the top-level of the repository.

In the terminal, enter that directory by:

cd learning-ehrql

So the directory should be:

/workspaces/YOUR_REPOSITORY_NAME/learning-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.

Use of 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 your 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, you will not get invoiced or charged.

If you run out of free quota, GitHub can 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.