BM3331 / BC5203

Working with github

All of the assignments and tutorials for this subject are managed through git and github. Both tools are widely used by bioinformaticians and learning to use them is an important aspect of this subject.

For your first assignment there is a fairly complex setup process required (steps 1-3 below). Fortunately you will only need to do this once.

1. Sign up for a free github account

To gain access to assignment/tutorial templates, and to submit assignments and tutorials you will need to sign up for a github account.

During the sign up process you will be asked to provide your email address and a username.

After verifying your email address with github and notifying me of your github username you will be ready to start assignments.

2. Generate a github Personal Access Token (PAT)

In order for your rstudio environment to securely communicate with your github account you need to provide a Personal Access Token (PAT). You generate a PAT on the github website. First login to github and navigate to Settings → Developer settings → Personal access tokens → Tokens (classic)

gh_find_creds

Click Generate new token and choose Generate new token (classic)

gh_new_token

Configure the new token.

  1. Give it a sensible name (eg BC5203 Rstudio)
  2. Set the expiry date to a short time after the end of this subject
  3. Essential: Give enough permissions to manage your repositories. Tick the boxes beside “repo”, “workflow” and “user” to give this token all abilities to manage and contribute to repositories.

gh_configure_token

Save the token! This is essential. The next screen will show your token. You must copy it now because this is the last time it will be displayed. If you lose your token you will need to make a new one.

Make sure you have this token ready for use in the next step

3. Setup rstudio to use your PAT

This step happens on the RStudio server (https://rstudio.bioinformatics.guide).

  1. Login to the server https://rstudio.bioinformatics.guide

  2. Open the RStudio console and run the following command

    gitcreds::gitcreds_set()

    Paste in the exact token that you generated in the step above. If it asks about your access method choose “github.com” and “https”.

  3. Finally you will need to tell github your name and email address. Here XX means your name (eg “Jo Bloggs”) and YY means your email (eg jo.bloggs@jcu.edu.au)

    usethis::use_git_config(user.name = "XX", user.email = "YY")

  4. Check that everything is setup properly

    usethis::git_sitrep()

    When you run this command it should print a bunch of information. Check for any errors. If you see errors you may not have your token setup properly

4. Access assignment repositories

As the subject progresses you will be given access to github repositories for your weekly coding tasks and your major assignment. Access works the same way for both.

Instructors will create assignments for each student based on their github usernames and the name of the assignment. For example, the first assignment is called unix-fundamentals. If your username is iracooke the instructor will create a github repository with the URL https://github.com/JCUBioinformatics/unix-fundamentals-iracooke. They will then make you a collaborator on the repository and you should receive an email from github inviting you to access. When you get these emails you should accept the access by clicking the link provided.

5. Clone the repository

Now you are ready to create a working copy of the repository that you were granted access to in step 4.

  1. Login to your RStudio cloud server (or open RStudio if you are doing things on your own computer).

  2. Select New Project from the project menu

    new_project

  3. Choose “Version Control” as the new project type

    vc

  4. Enter your repository URL and project directory details. You can easily find your repository URL by going to your repository page on github and clicking the green “Code” button.

    Note: Make sure you obtain an https url. This should be the default anyway.

    clone_or_download

After entering your repository details they should look something like this

clone_details

Note that in this example we have specified that the project should be created in your home directory. This is often the best and simplest option.

Once you have entered all the details click “Create Project”. When you do this RStudio will attempt to download a copy of your repository from github.

6. Submit your work

As you work on your assignment or tutorial you should regularly commit your changes to git and then push those changes to github. You can do all these things using the “git” menu in RStudio

rstudio_git

VERY IMPORTANT Make sure you commit AND push all your latest changes to github prior to the due date for each tutorial and assignment. Instructors will collect assignments by cloning directly from your latest version on github and any edits that you have not pushed will not count towards your assessment.

7. Check your progress.

As you work through your assignment you will typically run blocks of test code to check whether your answers are correct. When you commit and push your code to github it will automatically run all of the checks. You can view the status of the checks on github. Click the “Actions” tab and then click to view results of the “education/autograding” step.

view tests

Beyond this subject

A portfolio of high quality software is a valuable asset when looking for a job. Github and other code hosting websites provide opportunities for you to build such a portfolio. For example if you develop something that others will find useful you should consider publishing it on github. If you are looking for something to work on, consider contributing to an open source project. If your contribution is accepted it will show up in your profile and demonstrate to potential employers that you have the ability to collaborate and produce high quality code.

Explore some of the freebies available as part of the github student pack. Most useful is the unlimited private repositories from github