How to setup GitHub for a research project

This guide explains how to sign up to use GitHub.com for research and teaching.

This guide is aimed at...

• Research staff and students

Introduction

GitHub are the leading providers of cloud-based source code management and collaboration tools, including great support for version control, issue tracking, and code review, as well as the ability to manage software documentation and websites linked to the source code. Open source repositories carry no cost on GitHub and secure, private repositories are free for non-profit research. This guide explains how to sign up to use GitHub.com for research and teaching. For further information see:

• Support for UCL researchers to use GitHub

Create a personal account

First, users should create a personal account, using a ucl.ac.uk email address. You should use a .ac.uk or .edu email address, so that you will be able to sign up for free repositories for research. If you have already an account you can also add your ucl email to your account.

Visit github.com, and fill in your details. Have a look at GitHub's documentation if you need help. You should also read the details about how UCL Research Software Development can support you in your use of GitHub.

Create an organisation account

If you are a PI or leading a research group or consortium, or are acting on behalf of one, you have the option to create an organisation account for your research group. (Alternatively, you can just use the main UCL organisation) 

If you choose this option, have a look at the documentation and then create your organisation.

• You should choose the free "open source" tier for now - we will show you how to get free private repositories for your organisation later in this guide.
• For the "billing email", you should just enter any .ac.uk email address to which you have access.

• You may wish to add additional users to the "admin" team for your organisation on this page, by carefully entering their GitHub usernames.

  • Only include colleagues who need full admin access to the account; we will show you how to give other colleagues limited access later.

  • We recommend you include the user rc-softdev-admin at this point. You do not have to do this, but if you do, it will help us to support you in your use of GitHub.

If you need only open-source repositories, you can stop here.

The remainder of the instructions should be followed only if you need password-protected repositories which only designated users can access.

Register your organisation for free private repositories

You should now proceed to request the GitHub education discount to tell GitHub your organisation will be used for research or teaching.

1. On the first page:

   1. Select Researcher

   2. Choose Organisation account.

2. On the second page:

   • Choose the organisation account you created above
   • Select Research Group or teaching.

3. On the third page:

   • Enter the URL of the website of your research group, project or consortium.
   • Choose 20 private repositories, the maximum number allowed for an organisation account.

   • Answer No to the question "Is any part of your work done on a commercial/for-profit basis?".

     • If the answer to this question is yes, you will need to use UCL's paid central account for any work which does not meet this criterion. Please see below for details.
   • In the research funding box, enter "UK and European Research Councils" or similar, as appropriate to your research.

4. In the final page,

   • Ensure your ucl.ac.uk email address is shown in the drop down.
   • Upload a picture of your UCL card as proof of affiliation
   • Ensure the "School Name" is shown as University College London, University of London.
   • Finally, for "How do you plan to use GitHub in your research group?" you should enter "Management of researcher-written code for research data analysis, modelling and simulation," or a similar statement appropriate to your work.
   • Submit the form.

You should receive confirmation from GitHub within a couple of days that you have been granted a free Team plan, allowing 20 private repositories. Once this is received, you should proceed to create your first private repository, and add your research collaborators to your team.

Please forward this email to rc-softdev@ucl.ac.uk and add rc-softdev-admin as an owner of the organisation so that we can offer support, keep track of UCL groups' success in receiving private repositories and produce usage metrics across UCL.

If you are unsuccessful, please get in touch with us at the above address, so that we can provide you with access to UCL's central paid account.

Accounts for students and teaching

If you are an individual student who is not part of a research team, you should not create an organisation, but simply request the Student Development Pack that provides you unlimited private repositories for your personal account while you are a student and many other benefits.

The UCL Central GitHub Account

If you wish to carry out your work as part of the central UCL organisation, email rc-softdev@ucl.ac.uk, and we will then create a team for you within UCL’s central organisation, allowing you to create your private repositories and benefit from the paid Continuous Integration services.

You should expect this to be complete within two working days.

Your email should specify:

• Your name
• Your Github username
• Your UCL user ID
• A team name for your group, (no spaces)
• Name and Github username of one or more team maintainers.
• A repository name for your first project.
• Confirmation that you have read and understood the terms of use of the central account

Requests should come from UCL academic staff: research staff and research students should request that their PI or supervisor apply on their behalf, or forward to us confirmation that the PI has read and accepts these terms and conditions.