Skip to content

HTF Bioinf - How to start a new Gitlab project repo

We seek to standardise the setup of new repositories in Gitlab.

Check with the bioinformatics coordinator under which Gitlab group the new repo should belong. Ask the system owner (who has Maintainer role of that group) for permission to create the project.

First steps in Gitlab UI

  • In Gitlab, click the + and Create project. Typically you want to start with an empty project, i.e. not use templates. Make sure you add the project to the correct group.
  • Create a suitable brief name and a description.
  • Select public visibility level if in DPIPE
  • Click create project
  • Add a README.md file describing the project to the main branch. See instructions in Gitlab UI for creating a new repository.
  • If the project is located in DPIPE, add also a GPL-3 license file. This can be done via the button above the file listing. An OSS license like GPL-3 and public visibility are required for our free usage of Gitlab.

Setup of main branches and their protection

  • In Gitlab UI left bar, navigate to "Settings", "General".
  • In Visibility, select "Public" for Project visibility, and click "Users can request access"
  • Remove options not needed below, e.g. Git LFS, Gitlab pages. Click "Save changes" below.
  • Go to "Settings", "Merge requests". Tick "Merge commit with semi-linear history" in Merge method.
  • Allow squash commits (default). Save changes.
  • Go back to the repo, and create a dev branch for development. Can be done with + button in project.
  • Create CODEOWNERS file
    • In the project root, create a file named CODEOWNERS
    • Edit the file to contain e.g. * @yourGitlabUsername
    • Don't add too many users to this file unless really necessary. Maintainers and code owners who can approve merge requests should be few. The first user in CODEOWNERS is considered main responsible and go-to person for project.
    • Note that MR approval rules are set on the group level and that eligble approvers for changes to protected branches include CODEOWNERS
  • In the Gitlab UI menu on the left, select "Settings", "Repository"
  • Select dev as the default branch
  • Protect branches main and dev:
    • Allow Developers + Maintainers to merge
    • Allow no one to push. This will make MRs obligatory.
    • Toggle "Require approval from code owners" if toggle is present.

Later work

See the Development guide for suggestions on how to setup your project with Gitlab CI, Makefile, containers, package manager, etc. As the project develops, make the README more complete. E.g. google "what is a good README" and consider adding a simple tutorial for building and running tests.

Add a docs directory in the project root with further documentation. Here you can add for example more explanatory docs to help others understand your project and how it connects to other things. If it adds value, make a docs/diagrams directory with PlantUML C4 diagrams at least down to C4-container level. Edit the docsbuilder configuration file to include your project.

Access to projects

Public projects can be read by anyone, but any modification to code or issues requires membership in the group or project. Only users with Owners role can add members to groups, whereas Maintainers can add members directly to individual projects. Only developers at OUSAMG or trusted collaborators should have membership. This should normally be controlled at group level, with users given Developer roles. Alternatively, direct access to a single project can be granted if more relevant. Note that as an additional security measure, the main/master and dev branches are protected, such that MR approval by suitable approvers is required. Extra scrutiny is required when deciding if someone should be given approver status.