While "CTO" and "VP of Engineering" are the two roles that most commonly sign up for GitClear, our reports can provide useful visibility to most every stakeholder on a development team.

In this article, we'll review how to give access to various stakeholders on a development team. Then we'll dive into specifics about which reports and functionality is available to the different members from a team.

linkTable of contents

linkPrerequisite to GitClear access

Unless you're using the Enterprise Edition of GitClear, any team member that is invited to GitClear will log in via the git provider used by the team (i.e., GitHub, GitLab, Bitbucket, or Azure Devops). If you're giving access to technical team members, there's a good chance they've already set up an account on your git provider. However, if an executive or nontechnical Product Manager is invited, they might need to create an account on the git provider before they can log in to GitClear. As of July 2021, here are the instructions to add new users at the various git providers supported by GitClear:

On GitLab, you'll need to add the user to the project

linkTeam member roles

Screenshot modifying the role of a Developer on the "All Contributors" team

All access on GitClear is controlled by team "roles." The roles that you can select for your team members include:

Administrator. By default this permission is given only to the user that creates the GitClear account. A user with this permission has full access to all GitClear functionality, including the ability to create new teams and designate new Administrator-level users within the "All Contributors" team (the only team on which an Administrator can be designated).

VP Engineering / CTO. A user with the "VP Engineering / CTO" role has access to all GitClear reports, but does not have access to create and manage teams like an Administrator would. These users can manage entity-level settings, along with settings for any repo included within the team. This allows CTOs or VPs to set up ignored files, Code Domains (including e.g., tweaks to Line Impact for tests or documentation), and to generally dictate how Line Impact incentives should be administered on a team-by-team basis.

Executive. An Executive user has access to the same reports & settings that a "VP Engineering / CTO" does, but we set up different types of default notifications for Executives. Specifically, Executives are not automatically opted in to notifications about tech debt or commits that GitClear recommends reviewing.

Manager. This role is made for Project Managers and Lead Developers. Unlike the roles above it, the Manager does not have access to

The "Settings" tab of an Entity, Organization or Repo

Developer. Developer access is designed to allow Developers to review code, browse directories, and check how their own stats are changing over time. Unlike the roles above, a Developer's does not have access to view:

Stats for other developers than themselves (that is, you can filter on your own stats, but not on teammates' stats)

Line Impact editing tools

Stats for any repos that the Developer has not made a contribution to themselves

Contributor. This type of role is used when you want to create a team where you can oversee a developer's work without the developer having access to said team. Unlike other roles, a "Contributor" does not have access to GitClear--this role is a designation that exists only to follow the work of developers. Contributors are presented in the list of team members so they can be promoted to first-class team members if the Administrator should so desire. By default, any user who has commit activity processed will be added to the "All Contributors" team as a "Contributor."

The theme of these roles is that we seek to allow enough visibility for each role to be able to work more efficiently, but not so much visibility that the role could become distracted browsing through data that isn't relevant to their position.

Any role in the hierarchy of Administrator -> Executive -> CTO/VP of Engineering -> Manager can add or change team members up to the role beneath them. That is, a Manager can add or remove only Developers from a team, whereas an Executive can add/remove any role up to a CTO/VP of Engineering.

linkSetting up a team

There are no restrictions to the number of teams that an Administrator can set up. Therefore, we recommend creating a team for every group of stakeholders that work together on a project. The benefit of allowing you to control team member access through teams is that even if you have many teams working together in a large repo, each team will only see the work being done by their teammates.

To add a new team, visit Settings -> Teams & Users

Viewing all teams that have been created for an entity

The exception to this screenshot is if your role is "Manager." In that case, "Teams" gets its own top-level tab since "Settings" are not available to Managers.

If you're an Administrator, you can create a new team by clicking the "Create a new team" button at the bottom of this page and choose a name for the new team. This will leave you at a form like this one:

An empty team, immediately after being created

Once you've created your team, you have two options for how to get people on to it.

linkAdding users to a team

There are three options for adding users to a team.

linkRecommend path to add users: Use the "Get an invite link" button

Of the ways to add users to a team, the fastest & easiest way is to use the "Get an invite link" button in the team form. This allows you to fetch a link that can be sent to users with a particular role so that they can join your team:

Choosing an access level for an invite link

Usually the first step after creating a team is to create a link to invite Developers to the team. After choosing an access level, the link created can then be emailed to the development team to allow them to review their work and start tracking how their development focus is changing over time.

You can remove an invite link at any time. Users who used the invite link will remain on the team, but new users will not be able to join the team using the previous invite link.

linkAlternate path to add users: Add a repo to get a list of recommended users to choose from

If the "sending an invite" route doesn't appeal to you for whatever reason, the next easiest way to add users to a GitClear team is to choose the repo(s) that the team works in, and then choose from the users who are suggested (i.e., the contributors to those repos).

A list of "Suggested users" will be provided upon adding repos, so long as we can find email addresses associated with the committers in those repo(s)

In about 90% of cases, when the git provider has an email address on file for the committer, you should be shown user swatches like in the screenshot above. These users can be added as a batch by clicking the "Add all" link and choosing a role, or they can be added individually, with their role adjusted after adding.

linkAnother alternate path: Add users manually

The most involved path to add users to a team is to manually enter them through the "Add users" dialog. You can enter email addresses into this dialog to invite users to join a GitClear team with the access level you selected.

linkSpecifying repos available to a team

To limit the repos that should be visible to this team, click the "Edit repos" button near the top of the team form. Configuring which repos should be shown is desirable when you have developers on a team who are contributing to multiple projects, and you don't want their work on Project B to distract the members of Project A. By choosing which repos apply to the team, an Administrator can limit the scope of work that is presented to the team members, so they only see commits that were made to the repos in the list.

As a convenience, when an Executive, CTO/VP or Administrator adds new Contributors to the team, all of the repos those Contributors have participated in will be automatically added to the list of team repos. These can be removed as desired.

linkThe "All Contributors" team

For convenience, GitClear automatically creates and maintains a default team called "All Contributors," which is the superset of all committers and repos that have been imported to GitClear. It will look like this in the team list.

If you're managing a small team, you probably just want to add users to the "All Contributors" team. By default, developers who contribute to the repos in "All Contributors" are added as "Committers." You can change their role in the list to "Developer," or you can invite executives and senior management through the invite link if desired.

linkImmutability of Contributors and Repos

Since GitClear uses the All Contributors team as the single source of truth about all of the entity's work that is happening, it is not possible to modify the Repos or Contributors that are automatically added to the All Contributors team as work is processed.

If there are Contributors that you'd like to remove from being processed by GitClear, check out our instructions on "How to merge or exile a contributor."

linkScope of team role access & examples

Members of a team can view git activity for their teammates, so long as that teammates' work occurred in one of the repos that was chosen for the team. Any role in the hierarchy of Administrator -> Executive -> CTO/VP of Engineering -> Manager can add or change team members up to the role beneath them. That is, a Manager can add or remove only Developers from a team, whereas an Executive can add/remove any role up to a CTO/VP of Engineering.

To help build intuition for how to configure your own teams, here are a few examples of how GitClear would work for common situations:

linkExample 1: Committer contributing to two teams

Let's say that a committer "Stan" participates in two git repos, "ai-company" and "vr-company". The manager of "VR Company" doesn't want Stan's sensitive work to be visible outside his team. This is possible by creating a GitClear team for each repo, and adding the repo to its respective team. Then, any members of the "VR Company" team -- even if they are Executives or the CTO of the VR Company -- will not be able to see any activity that Stan contributes to the "ai-company" repo.

Conversely, members of the "AI Company" GitClear team will only be able to view Stan's contributions to their "ai-company" repo.

linkExample 2: A shared library used across many projects

A company "Widget Co" has three projects that all contribute to, and consume, a repo called "widget-lib." We'll call the projects Project A, Project B and Project C.

To allow Project A's Project Manager to see when their developers are working on "widget-lib," the Administrator can add the "widget-lib" repo to Project A. This will make it easy to see how much of Project A's development work is being done on "widget-lib" relative to the repo dedicated to Project A (presumably the main focus of Project A's Developers).

If the Administrator would like for all of a company's developers to be able to view all contributions happening across all teams in "widget-lib," they could create a team called "Widget Library Development." That team could include only the "widget-lib" repo, and could have all developers from the company added at the "Developer" role. When they switch to that team context (see "Switching between teams as a viewer"), they will be able to view useful dev tools like Commit Activity Browser and the Directory Browser with the activity of every developer that has contributed to the "widget-lib" (and only the "widget-lib") repo.

linkExample 3: Mapping GitClear Teams to a medium- or large-sized company

Generally speaking, GitClear Teams are most useful when they mirror the organization within the company itself. Across GitClear customers, we find many companies that divide their developers into teams of 3-10, usually with one Lead Developer and one or two Project Manager(s). This is the canonical case the team viewer was built for: you create a team, name it to reflect however you refer to this collection of developers internally, and then send a link to the team's developer email list inviting users from the team to click to join a team that you have set up for them.

The Lead Developer and Project Manager would both be invited to this team with "Manager"-level access so they could review work across all of the team's developers.

If desired, the CTO, VP of Engineering, and other executives, can either be added individually to each team, or they can be added to the "All Contributors" team, which will allow them to see the global stats for the repo, organization or entity that they choose to view.

linkSwitching between teams as a viewer

The toggle between teams is located in the upper right of any page where team scope is applicable

When browsing GitClear, the current team context will be shown in the dropdown in the upper-right corner of each page. Changing the selected team will update the developers and repos shown within the reports being visited.