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 GitHub, you'll need to ensure that the user is added to the repositor(y/ies) in the Collaborators menu
On GitLab, you'll need to add the user to the project
On Bitbucket, you'll need to grant the user access to your repositor(y/ies)
In Azure, you'll need to add the user to the organization and project
linkTeam member roles
Adjust a team member's role by visiting the Settings -> Teams page, then clicking on a team to open it and view its members
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. This user can do everything.
VP Engineering / CTO. This user can modify their team in any way, but can not create new teams. This user can edit all company settings, like ignored files and Code Domains.
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.
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. A user designated as a Manager will only see the repos and developers associated with the team they were assigned to.
Developer. Developer access is similar to Manager access in that it does not allow viewing entity settings, but it does allow viewing any team report in the context of their team and repos.
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.
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 is no cost to set up as many teams and users as you please. We recommend creating a team for every group of stakeholders that work together on a project. This allows you to circumscribe the repos and developers that are visible to each GitClear user you invite.
To add a new team, visit Settings -> Teams
Viewing all teams for the entity as an Administrator
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, then enter a name for the new team. This will bring you to a form with the following options:
A team named "Tony's Angry Mob," shown immediately after being created. Executives from the "All Contributors" team are automatically added to new teams so they can drop in as they please.
Now that you've created a team, read on to learn the options for getting users into it.
linkAdding users to a team
There are three options for adding users to a team.
link1. Recommend path: 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:
Choose an access level to be associated with users who are invited through this link
After choosing an access level, the link created can then be emailed to the users selected, and when they sign up they will get access only to see only the repos and developers you associated with this team.
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.
link2. Alternate path: Add a repo, get a list of recommended users to choose from
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.
link3. Alternate path: Add users manually
The most involved way 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.
link4. Alternate path: Via CSV or API
We have an open offer to build a CSV importer for teams if we have a paying customer who would use it. It would also be trivial for us to allow configuring team access via API, but as yet we have not had a paying customer who has committed to use it.
linkSpecifying repos available to a team
Click the "Add repos to this team" button to open a form allowing repo selection
To limit the repos that should be visible to this team, click the "Edit repos" or "Add repos" button on the team form.
By choosing which repos apply to the team, an Administrator limits the scope of work & reports that are presented to the team members, since team members will ONLY see activity where the team's specified developers make contributions to the repos listed. For example, if Tony's Angry Mob is set up as follows
A hypothetical team with one developer (Chima Flom) and one repo (faststartup/marketplace)
Then the members of this team would see activity only when Chima Flom contributed to the faststartup/marketplace repo. If Chima Flom makes a commit to a different repo, or if some other contributor makes a commit to faststartup/marketplace, that commit activity will be invisible to those who are viewing reports in the context of this team.
linkThe "All Contributors" team
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 on the Settings -> Teams page.
If you're managing a small team, you probably just want to add users to the "All Contributors" team. By default, any developer who has made a commit in any imported repo will be shown, initially with the "Contributor" role, on the "All Contributors" team.
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
Upon logging in to GitClear, a non-Administrator team member will be sent to the Commit Activity Browser (default GitClear report) with their team selected by default. On this report, along with all other visited, the team member will only see aggregated data that occurred in one of the repos that was chosen for the team.
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. If we take the team configuration shown previously:
An example team where a repo limits what activity is shown
In this screenshot, the faststartup/marketplace repo is equivalent to the vr-company repo, where if Joe Schmoe logs in to GitClear, he wouldn't see the commits that Chima might be making to repos outside of faststartup/marketplace.
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 choose the "Widget Library Development" team from their Team Selector, 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. We have a separate help page dedicated to describing how to leverage the Team Selector.