Organizing Projects

Remote services provide a range of management features that extend beyond individual repositories. These features include robust tools for project management and access control. They typically offer various methods to organize developers and other contributors into entities with defined roles and permissions within the platform.

In this section, we will explore how GitHub and GitLab enable the structuring of contributor groups, highlighting how each platform’s approach enhances access management and fosters collaboration.

Challenges Research Groupy May Encounter

Imagine a research group at a university, bustling with brilliant minds and groundbreaking ideas. However, their collaboration is hindered by a chaotic workflow. Emails are overflowing with attachments, version control is a nightmare, and crucial updates are often lost in the shuffle. Team members frequently overwrite each other’s work or share code snippets by email, leading to frustration and wasted time.

Tasks are managed haphazardly, with no clear system to track progress or assign responsibilities. Important milestones are missed, and the lack of standardized documentation of implementations or even ideas makes it difficult for new members to get up to speed and can lead to knowledge drain when team members leave. Data integrity is compromised, and integrating contributions from different team members is a constant struggle.

GitHub’s Organization Structure

Key Elements

Users Organizations Teams Repositories

Individual accounts that can own Organizations, (nested-)Teams, and Repositories. They can be assigned to different project management elements and roles like Issues, Pull Requests, Milestones, Projects, etc.

Details

• Individual accounts that can access and contribute to repositories.

• Can be assigned different roles & permissions within Organizations, (nested-)Teams and Repositories.

Setting up a GitHub Organization

Roles in Organizations:

• Read: Can view repositories and issues.

• Triage: Can manage issues and pull requests.

• Write: Can push code, manage issues, and pull requests.

• Maintain: Full access to manage non-destructive, non-sensitive settings.

• Admin: Complete control over the repository and its settings, incl. managing security and deleting the repository.

In GitHub Organization members can have different access levels to the repositories that are owned by the Organization. Organization owners can manage the access rights of members and create Teams to group members with similar roles or responsibilities. They can also set base permissions for the Organization and its repositories. Organization owners have admin access to all repositories and can manage the Organization’s settings.

Enterprise Cloud:

GitHub Enterprise Cloud offers additional security features and compliance tools for organizations, i.a. SAML single sign-on, automated security updates, and advanced auditing, and Organization specific roles.

For a small organization, like a research group or small company, we suggest the following approach:

1. Create an Organization:

• Create a new Organization to represent your research group.

  Note

  Assign multiple Owners to the Organization. If an organization only has one owner, the organization’s projects can become inaccessible if the owner is unreachable.

• Unlike in GitLab, the visibility of an Organization in GitHub is always public. However, repositories owned by the Organization can be private.

2. Create Teams:

• Create Teams to represent different research groups, projects, or labs within the Organization.

• Assign members to the Teams based on their roles and responsibilities.

  Tip

  Assign two or more Organization members as Team Maintainers to help manage the Team’s settings and permissions.

• Teams can be nested within other Teams to reflect the research group’s hierarchy.

3. Invite additional Users:

• Add external collaborators who are not part of your Organization directly to the corresponding Repositories.

GitHub’s Organization Structure in Action

In an academic context, GitHub’s organization structure can be leveraged to streamline collaboration and project management. Here’s how it might look:

• Organization Creation: Your university’s research lab could create an organization on GitHub to host various research projects. The faculty members could be the owners of the organization, overseeing the projects and managing access.

• Team Formation: Create teams within the organization for different research groups or projects. Each team would have access to specific repositories based on their roles and responsibilities. This might be useful for managing permissions and collaboration within the lab. For example, a team of students working on a specific project could have access to the corresponding repository.

• Repository Management: Each research project could have its own repository within the organization (or multiple repositories). These repositories could contain code, data, manuscripts, and other project-related files. By using repositories, you can maintain version control, track changes, and collaborate effectively on research projects.

• Progress Tracking: Track the research project’s progress using issues, project boards (which can be linked to multiple repositories), and pull requests within the repositories. This would help in managing tasks, tracking milestones, and reviewing contributions from team members.

Collaborating with External Partners

Invite collaborators to specific repositories within the Organization, enabling them to contribute to the project. This can be particularly useful when working with industry partners, other research groups, or open-source communities.

GitLab’s Organization Structure

GitLab implements a nesting approach when it comes to access rights and structuring multiple projects and related users. It relies on only two building blocks, Users and (Sub-)Groups, for managing access rights.  

In GitLab nested usergroups are used to manage access rights to repositories.

Key Elements

Users Groups Subgroups Projects

Individual accounts that can own Projects and roles in other Projects or (Sub-)Groups.

Details

• Individual accounts that can access and contribute to repositories.

• Can be assigned different roles & permissions within (Sub-)Groups and Projects.

Setting up an Organization

Roles:

• Guest: Limited access to view Issues and Merge Requests.

• Reporter: Can view and create Issues, but cannot push code.

• Developer: Can push code, manage Issues, and Merge Requests.

• Maintainer: Full access to manage the Project and settings.

• Owner: Complete control over the Group and its Subgroups.

GitLab’s approach to manage access control requires some care in order to create a organizational setup that facilitates collaboration and project management. The key aspect to take into account is the inheritance of Members (i.e. Users) along with their roles (i.e. access rights).

For a small organization, like a research group or small company, we suggest the following approach:

1. Create a Group:

• Create a new Group to represent your organization.

• Set the visibility level.

  Note

  Restrictions in the visibility are inherited, i.e. in a private Group you can only have private Projects. However, in a public Group it is possible to have private Projects.

• Decide on the transparency level within the group by identifying a default role for members of the Group.

  Tip

  Developer is a good default role, as it allows to view all Projects and suggest edits without being able to change the content of a Project completely.

• Invite all permanent group members.

• Designate 1-2 Users with elevated privileges. We recommend to have more than one Owner and some Maintainers.

2. Create Subgroups

• Fill in the short description to clarify what this Subgroup is about.

• Designate 1-2 Users with elevated privileged (i.e. designate another Owner and maybe some Maintainers)

  Tip

  You can invite Users that are already part of any parent (Sub-)Group again and “escalate” their role in this Subgroup. In doing so you can designate Owners or Maintainers of only Subgroups.

  Note

  The inverse is not possible: You can only give a User more rights than what was already inherited from the parent (Sub-)Group.

3. Invite additional Users:

• Add external collaborators and short-term members of your group directly into the corresponding Subgroups.

  Tip

  It is also possible to add entire (Sub-)Groups which can be a great setup for a collaborative project between two or more research groups.

4. Gradually escalate Privileges.

• Elevate the privileges of Users in Subgroups to make sure that the members of a Subgroup can take advantage of GitLab’s remote features to the fullest extent.

• Think of re-inviting members of parent (Sub-)Groups to elevate their roles.

GitLab’s Organization Structure in Action

In an academic context, GitLab’s organizational structure can be leveraged to streamline collaboration and project management. Here’s how it might look:

• Group Creation: Your university’s research lab could create a Group on GitLab to host various research projects. Faculty members could be assigned the role of Owners of the Group, overseeing the projects and managing access.

• Sub-Group Formation: Create Subgroups within the main Group for different research areas or projects. Each Subgroup would have access to specific repositories based on their roles and responsibilities. This structure is useful for managing permissions and collaboration within the lab. For example, a Subgroup for a specific research project could have its own dedicated repositories.

• Repository Management: Each research project could have its own repository within the relevant Subgroup (or multiple repositories). These repositories could contain code, data, manuscripts, and other project-related files. By using repositories, you can maintain version control, track changes, and collaborate effectively on research projects.

• Progress Tracking: Track the research project’s progress using Issues, issue boards (which can aggregate all Issues in a Subgroup), and Merge Requests within the repositories. This would help in managing tasks, tracking Milestones, and reviewing contributions from team members.

  Note

  In some cases, the administrative hierarchy of the faculty is not suitable to be mirrored in GitLab’s Group/Subgroup structure. For example, if a faculty member is barely involved in hands-on research, a second Group-Owner might relieve them of the burden of managing GitLab access rights.

Collaborating with External Partners

Invite collaborators to specific Projects or Subgroups within the Group, enabling them to contribute to a project. This can be particularly useful when working with industry partners, other research groups, or open-source communities.

Differences Between GitHub and GitLab

Project \(\neq\) Project

In GitLab a repository is represented in a Project while on GitHub it is a Repository.

What is refered to as Project in GitHub shares more similarities with a Subgroup in GitLab.

Access Rights and Sub-Groups

Feature	GitHub	GitLab
Access Control	Managed through nested Teams and Repository settings	Managed through Subgroups and Repository settings
Permission Levels	Read, Triage, Write, Maintain, Admin	Guest, Reporter, Developer, Maintainer, Owner
Inheritance	Permissions are inherited from organization-level settings to Teams and child-Teams.	Subgroups inherit permissions from parent (Sub-)Groups, but cannot revoke them
Additional Rights	Can assign different permissions to Teams	Can grant additional rights in Subgroups