The good GitHub workflows depends on many factors, such as the size of the team, the nature & composition of the team, the complexity of the project, the toolchain used by the team, and the culture, etc. Therefore, it is important to pick a workflow that suits the team & project the best. It is probably good to start simple.

Workflow options for academic research projects#

I’d say the best option to start with first is the second one with branches + PRs.

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 pushing 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. 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 small team with short-lived branches#

This can be a good alternative for a very small team and work with a bigger team as well. This workflow is probably the best balanced option, with the benefits of expertise spill over and education through code review. 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 outlines 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.

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.

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

If the stake 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 be likely 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.