Depending on your git provider, GitClear may offer the means to automatically import teams, users, and repos from your existing git provider.
linkInitiate a team or repo import
There are two options to access the GitClear sync.
linkVia team page
Visit Settings -> Teams -> Sync teams to access the team sync form.
Currently, only GitHub is supported for importing teams. We can add investigate adding support for additional git providers upon the request of an Elite customer.
After clicking the "Sync" button, you will be taken to your list of previous team syncs (if any exist) or the form to initiate a new team sync (if you have not previously initiated one).
A list of pending Team Sync Requests is shown, if there are currently outstanding requests
linkVia "Add a repo" page
If you visit the "Browse" tab and click "Add a repository," the ensuing page should have a button to "Sync recently active repos," as long as you have an established connection to GitHub.
A button to sync recent repos should be present atop the page when a GitHub connection has been made
linkTeam & repo sync form
The sync form provides a handful of options:
Options presented by the team/repo sync form
The tooltips next to each option give more detail on their effect.
linkTeam imports
Git providers like GitHub let users set up teams for access management. These teams are composed of team members (users of the git service) with an assigned access level (e.g., "member," "maintainer") and repos for which the team has access.
linkBasic imported content
Regardless of which import settings are chosen on the team sync form, all team imports will at least (to the extent your token allows) 1) create teams with names that correspond to the git provider 2) create contributor (also called "committer") records in GitClear that correspond to each user on the git provider. This ensures that you will have teams on GitClear that separate committer work along the same dividing lines that were set up on the git provider.
For example, if you have a GitHub team called "Library Developers," in a GitHub organization called "Albert," GitClear would import a team named "Library Developers (Albert on Github)". That team would be stocked with all of the same developers from the GitHub team, so you would be able to view charts that show progress from the Library Developers team, to the extent that the repos for that team were imported to GitClear.
linkOption: "Remove absent team members from GitClear"
This configuration option controls whether GitClear will remove contributors from the team when they can't be found on the GitHub team. This option is useful if you plan to repeatedly sync teams with GitHub, and you expect to have developers periodically leave the team (as is common in any company). When this box is checked, the team size can shrink, not just grow.
However, if you would like to adapt the team on GitClear so that it includes developers who aren't on the GitHub version of the team, you would want to leave this box unchecked so the customer committers you added wouldn't be removed.
linkOption: "Invite newly discovered users to GitClear"
Ostensibly, when this option is checked, we will send invites to team members so that they can log in to GitClear with access corresponding to their GitHub access. Assuming that, on GitHub, you assign the default "member" role (as opposed to "maintainer"), the team member on GitClear would be assigned the "Developer role" within the team that was imported. This would imply that the developer could view stats for their team, and stats for themselves, but would not be able to filter stats of their other team members unless they requested access to their teammates' data. They also wouldn't be able to see any stats for repos beyond the set that were visible to their GitHub team.
The previous paragraph was qualified with the word "ostensibly" because, in practice, GitHub only shares email addresses when the developer has opted in to allowing their email to be viewed. Since relatively few developers enable this (around 20-30%), the majority of developers can't be automatically invited because GitClear doesn't possess their email address.
In practice, there is a final step to recreate the same team structure on GitClear as GitHub, and that is to send your developers an invite to log in to GitClear after their data has been imported. GitClear assists in this process by providing a link that can be emailed to developers after a team import has recently completed:
On the first login after a completed team sync, the user to request a team sync can copy an invite link to their clipboard, to be emailed
After clicking the button to "Copy an invitation link," open your email client, and paste the link into an email that is sent to the developers who should receive access. This will enable your team to see their own stats, the first step toward optimizing them.
Remember: If you do not email this link to your coworkers, they won't be able to log into GitClear. Thus, they won't be able to see their stats nor have the opportunity for self-improvement via data & goal-setting.
linkOption: "Automatically sync with these settings every day"
Elite subscribers can keep their GitClear teams perpetually in sync with the teams at their git host by checking this option. This benefit means that Elite subscribers only need to manage the membership of teams on one site (their git provider) instead of two (their git provider and GitClear).
linkStopping automatic sync
To stop automatically syncing teams daily, visit your Team Sync page (by filtering your Entity, then Settings, then "Teams," as described above), and click the button that will be present if (and only if) daily sync is currently active:
A button to stop automatic sync is present when an entity has automatic team syncing enabled
link
linkRepo imports
We recommend keeping all of your active git repos synced to GitClear, to ensure visibility across projects (even if repos are in separate organizations) from a single location (your GitClear entity). The "Sync repos can initiate import" option enables a complete sync of repos that have been recently active on your git provider.
Imports will be queued for any repos associated with the team that have activity within the past 30 days. Along with skipping repos that haven't changed recently, GitClear will stop importing repos if you reach the repo limits that correspond to the GitClear subscription level.
If the team sync begins import of undesired repos, read below about how to stop those imports.
linkEditing the result of an import
Sometimes there are teams or active repos at your git provider that you do not want to analyze on GitClear. To make it more convenient to tailor your team sync to the exact content you want, we send an email when a team sync that you queued has completed. In the email, you'll find a button that takes you to a summary of the sync. It might look something like this:
When reviewing the details of a team sync, you can quickly snip out teams or repos that shouldn't be imported (no page reload needed!)
Only teams and repos that were created by this specific team sync request will be listed for removal. If you are reviewing the results of a team sync where most of the content is not new, you won't see "Remove" links next to the previously-imported content, only the newly-imported content. If you really want to delete a team or repo that is listed, you can click the link to the resource and delete it from there, or you can open the sync request in which the resource was created.
linkSupporting non-GitHub team sync
If you have teams set up on a git provider like Bitbucket, and you would like to sync those teams to GitClear, please drop us a line at support@gitclear.com. Especially if you are an Elite subscriber, we can help investigate how much work would be required to sync teams from other git providers.
linkWhat will team sync automatically remove from its past imports?
Generally, syncing teams is meant to introduce users and repos to GitClear. However, if you prefer to manage teams on your remote git provider, it's only a matter of time until you will have committers or repos that should no longer be present on GitClear.
As of initial implementation, we do not have a mechanism to remove synced teams, since it is difficult to ascertain whether a team isn't returned to our API because the team was removed, or because the token we used was from a user who happened to have insufficient access to view all teams.
Team members can be removed, by selecting the "Remove absent team members" option when queueing the team sync.
Repos will not be removed from GitClear, but if you have clicked to "Sync repos," and a repo's association with a team is removed, then GitClear will delete the association between that team and repo, so that members of the team no longer see stats about the repo.