Many academic teams tend to fall into one of two traps with GitHub: either they treat it as a shared (or sometimes not even shared!) Dropbox—everyone pushing to the main branch and hoping for the best—or they try to adopt a full open-source workflow with strict code review, which quickly becomes too much friction for a small team. I think there’s a middle ground that works fairly well in an academic, small-team setting.

But, remember that the right workflow depends on the size of the team, the nature of the project, the toolchain, Git mastery in the team, and its culture.

Workflow options for academic research projects#

A small team with short-lived branches (recommended)#

This is probably the best balanced option for most teams, with the benefits of expertise spillover and education through code review. It works for very small teams and scales to bigger ones. Consider each branch & pull request as a work session. For everyone on the team, do:

1. Create a local branch for a work session.
2. Push the branch & make a draft pull request. Write a good title for the purpose and outline the todo items. Note that the actual work for the PR has not been done yet. Marking as a “draft” prevents immature merging. Assign reviewer(s) so that they are aware of the PR.
3. During a work session, keep committing & pushing to the open PR (yes you can do that) until ready or until wrapping up the work session.
4. Reviews can happen multiple times during (3) and this is often better because reviewers would only need to look at a small amount of changes.
5. Merge the branch. If code review creates too much friction and PR becomes too big, consider merging quickly (even without review) after a short wait period.
6. Optionally, delete both local and remote branch (this can be done automatically—there is an option in the repository setting).
7. Pull the main branch and go back to (1).

The reason for (2-3) is to keep the team aware of what everyone is on, which helps avoid conflicts or duplicated efforts.

Regarding (4), reviews are very good for catching errors and the spillover of expertise in the team. Yet, it is also a big commitment for the reviewers and often challenging to institute. While it is important to encourage reviews, it is probably not a good idea for a small team to make a strict policy about reviews, which can significantly slow down progress and introduce too much friction. If it is difficult to get a review in time, it is probably better to move on with no review or a much more simplistic review.

Regarding (5-7), although deleting the branch every time may not always be the most efficient or “right” option, I find it the cleanest and easy-to-understand workflow, especially for Git beginners. If you don’t delete the local branch, it will require rebasing or merging later and that can easily lead to the git hell™. This conflict issue becomes less significant if you use coding agents like Claude Code because they are masters of Git. So either way can work well.

One important rule of thumb: don’t let branches live too long. The longer a branch diverges from the main branch, the harder it becomes to merge. Try to keep branches short-lived—ideally merged within a day or two. If a branch has been sitting open for multiple days, it’s a sign that the scope is too big or that it needs to be broken up. A stale branch is a merge conflict waiting to happen.

Given that requiring more advanced Git knowledge is a substantial extra overhead to the team, I recommend this as a reasonably simple and frictionless workflow that works for most teams.

Push to the main branch (Github as a shared folder)#

If the team is very small (e.g., one or two people) and it is ok to consider GitHub as a “synced folder”, then the simplest workflow is to give full access to everyone and just push every change to the main branch. This workflow is the simplest and doesn’t require much knowledge of Git or GitHub.

This is a simple solution but it may create hard-to-merge conflicts especially if the team members are not diligent enough to sync often. There is also no built-in mechanism for code review or visibility into what others are working on—you only find out when something breaks or conflicts. To avoid conflicts, try to be agile—don’t keep your unpushed changes for long. Keep the GitHub and local clone as synchronized as possible.

1. Start a clean work session by pulling all changes
2. Make small commits as you go
3. Push & pull often
4. Repeat

A larger team with strict code review (open source model)#

If the stakes of the software is high and/or the team is large, the team may institute a more strict process that resembles common open-source workflows. In this workflow, there will likely be a set of core developers who are in charge of reviewing and merging new code. They will be the gatekeepers. Contributors will be asked to create clean, self-contained pull requests—rather than a ‘work session’—which will then be reviewed and merged by the core developers.

I think this is often too restrictive in academic research projects carried out by a small team. The overhead can become significant and can create frequent merge issues that can drastically slow down the team.