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
  • how to run some OpenSAFELY features in GitHub Codespaces
  • how to get ready to run the ehrQL tutorial
  • how GitHub's free user quota for Codespaces works

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 sign up process on GitHub's site.

Sign in to GitHub🔗

Whether you have created a new GitHub account, or are using an existing GitHub account, sign 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. You begin by clicking the "Use this template" button.

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.

It may take a couple of minutes before the codespace is ready for use.

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

Briefly, when you first open Visual Studio Code, you will see:

  • on the left, the project's files and folders in the file explorer
  • a terminal at the bottom-right
  • a file editor at the upper-right; this initially remains blank until you open a file

There are other elements to the user interface. Refer to the explanation in GitHub's documentation for more details.

Working with files🔗

Editing code🔗

The file explorer shows the contents of your code repository.

You can open files and folders by clicking on them.

Saving files in the codespace🔗

Currently, the codespace is configured to autosave files on change.

Reverting changes to files in the codespace🔗

You can do this via the Visual Studio Code interface.

  1. Select the Source Control panel on the left-hand side
  2. You should see a list of the changes.
  3. You can right-click on each of the changes and choose to discard them. This reverts the files back to how they are in the current version of the repository.

Info

For users comfortable with command-line Git, you can use git in the terminal to work with the repository, including reverting changes.

This page will not cover use of command-line Git.

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, you must 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.

Run the OpenSAFELY command-line interface (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.

Run the example project🔗

The research code repository that you created already has an OpenSAFELY project in it. We can try this out to show that everything works as if we had installed the OpenSAFELY CLI.

Ensure you are in the correct directory to run the project🔗
  • By default, the terminal that has opened should be in the correct directory (folder) that contains the project.yaml file.
  • This directory is /workspaces/your_repository_name where your_repository_name should be replaced with the name that you chose.
  • You can check the current working directory by referring to the terminal prompt.
  • If necessary, you can change directory to the correct directory by typing: cd /workspaces/your_repository_name where your_repository_name should be replaced with the name that you chose.
Use OpenSAFELY CLI to run the example project🔗
  • In the Visual Studio Code terminal, type opensafely run run_all and then press ++Enter++ to run the existing project.yaml.
  • This may take a few moments to download the required Docker images, before the project is run.

You will see some message that should end something like:

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

Follow the ehrQL tutorial🔗

The ehrQL tutorial assumes that you are working on your own computer, where you would be familiar creating files and folders.

It requires you to create a learning-ehrql directory, you can either:

  • In the Visual Studio Code interface:
  • Go to the file explorer outside of a directory and right-click..
  • From the menu, select "New Folder…".
  • Name the folder learning-ehrql.
  • Right-click and select "Open in Integrated Terminal".
  • A new terminal will open up in the correct directory. You can see the list of open terminals in the bottom-right.
  • Or, in the terminal:
  • Ensure that the terminal is in the /workspaces/your_repository_name directory by checking the command prompt and typing mkdir learning-ehrql and pressing ++Enter++.
  • Change to the learning-ehrql directory by typing cd learning-ehrql and pressing ++Enter++.

In either case, the terminal prompt should be /workspaces/your_repository_name/learning-ehrql. This will have you ready to run commands for the ehrQL tutorial.

You can now work through the ehrQL tutorial "Installation and setup" page. TODO: add link Note that you can skip the installation steps of the ehrQL prerequisites.

Other features for development🔗

Running Jupyterlab🔗

  • In the Visual Studio Code terminal, type opensafely jupyter and then press ++Enter++ to launch the Jupyterlab server.
  • This may be useful to develop Python-based analyses interactively based on dummy data outputs.
  • 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. The "Running Process" entry should start "/usr/bin/docker-proxy…" Click on that link to access the Jupyterlab server.
  • You can edit files in your codespace from within Jupyterlab.

!!! warning

  Unlike the Visual Studio Code interface,
  files do not save automatically in Jupyterlab.
  You must save them manually.

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