GitHub for Scientists

GitHub is a website that hosts Git repositories online. It makes your code accessible to collaborators, reviewers, and the wider scientific community. This page covers the essential GitHub skills for scientists.

Creating a Repository on GitHub

Sign in to GitHub and click the + button to create a new repository.

You need to choose between public and private:

• Public repositories are visible to everyone. Use these for published papers and open-source tools. Public repos are free.
• Private repositories are only visible to you and people you invite. Use these for unpublished work or sensitive analyses.

Give your repository a descriptive name like rnaseq-drug-response rather than project1. Add a short description so others know what the project does.

Connecting Your Local Repo to GitHub

After creating a repository on GitHub, connect your local Git repository to it:

git remote add origin https://github.com/your-username/your-repo.git

This tells Git where to send your commits when you push. The name origin is a convention for the primary remote repository.

Verify the connection:

git remote -v

Pushing Code to GitHub

Upload your local commits to GitHub with git push:

git push -u origin main

The -u flag sets origin main as the default upstream. After the first push, you can simply run:

git push

Push regularly. If your laptop dies, your code is safe on GitHub.

Pulling Changes from GitHub

Download changes from GitHub with git pull:

git pull

Use this when collaborating with others. Always pull before you start working to avoid merge conflicts.

Cloning Someone Else’s Repository

Download a complete copy of any public repository:

git clone https://github.com/nf-core/rnaseq.git

This creates a local directory with the full repository history. You can browse the code, run the scripts, and even modify them locally.

The README File

Every repository should have a README.md file. This is the front page that GitHub displays when someone visits your repo.

A good README for a scientific project includes:

• What the project does. One or two sentences describing the analysis or tool.
• How to run it. List the dependencies and provide the commands needed to reproduce results.
• What data it needs. Describe the input data and where to get it.
• Who to contact. Your name and email for questions.

Write the README in Markdown. GitHub renders it automatically.

Releases and Tags

Mark specific versions of your code with tags. This is critical for reproducibility.

git tag v1.0-paper
git push origin v1.0-paper

Tags create a permanent snapshot. When a reviewer asks “which version of the code produced Figure 3?”, you can point to the tagged release.

On GitHub, go to the Releases page to create a formal release from a tag. You can attach supplementary files and write release notes.

GitHub Issues

Issues are a built-in task tracker. Use them to:

• Record bugs you find in your analysis.
• Track to-do items for your project.
• Document decisions about methodology.

Even on a solo project, issues help you organize your work. Write a clear title and a brief description of the problem or task.

Collaborating with Others

Adding Collaborators

For private repositories, go to Settings > Collaborators and invite people by their GitHub username. They get read and write access to the repository.

Pull Requests

Pull requests let you propose changes and get feedback before merging. The workflow is:

1. Create a branch for your changes.
2. Push the branch to GitHub.
3. Open a pull request on GitHub.
4. Your collaborator reviews the changes.
5. Merge the pull request when approved.

Even in small teams, pull requests create a record of what changed and why. They also catch mistakes before code reaches the main branch.

Licensing Your Code

Without a license, others legally cannot reuse your code. Add a LICENSE file to your repository.

Common choices for scientific code:

License	What it allows
MIT	Anyone can use, modify, and distribute. Very permissive.
Apache 2.0	Like MIT but includes a patent grant.
GPL 3.0	Others must share modifications under the same license.

MIT and Apache 2.0 are the most common choices for scientific software. If you want others to use your code freely, pick MIT.

GitHub and Journal Requirements

Many journals now require code availability statements. A GitHub repository with a tagged release satisfies this requirement.

Best practices for publication:

• Tag the exact version used to generate results in the paper.
• Include a README with reproduction instructions.
• Archive the repository on Zenodo. Zenodo creates a DOI for your repository, giving it a citable identifier that will not break if GitHub changes.
• Reference both the GitHub URL and the Zenodo DOI in your paper.

Tip

Zenodo integrates directly with GitHub. Enable the integration once, and every GitHub release automatically gets a DOI.

Summary

• Create repositories on GitHub to back up and share your code.
• Push regularly to keep your work safe.
• Write a README so others can understand and run your code.
• Tag releases for reproducibility.
• Add a license so others can legally reuse your work.
• Use Zenodo to create DOIs for publication.
• Pull requests enable code review even in small teams.