1. Help Center
  2. Getting Started

Team Management

Instructions for Team Management and configuration in Swarmia.

Creating teams

After completing your initial Integrations, you'll first want to create teams and build your organization. This can be done by navigating to team settings

Defining team members

You can add three kinds of members to teams:

  1. GitHub users
    1. You can search and add individual GitHub users to teams in Swarmia.
    2. By default, the search only returns users that currently belong to your GitHub organization. If you need to add users outside of your GitHub organization (e.g., contractors) or historical users (e.g., previous employees), you can find them by searching with their exact GitHub username.
  2. GitHub teams
    1. You can add whole GitHub teams as team members to automatically keep your teams up-to-date when GitHub teams are updated. GitHub also provides an API to manage the teams, which can be used to automate team management in Swarmia.
  3. Contributors not belonging to your GitHub organization
    1. In certain situations, like when working with contractors, it can be beneficial to be able to add contributors from outside of your company's GitHub organization to your Swarmia Teams.
    2. To do this, you will just need to type in their exact GitHub username into the search field.
    3. This adds their contributions to your team's metrics in Swarmia, but they will still not have access to your Swarmia instance without access to your GitHub organization. 

Setting up hierarchies 

Creating the team hierarchy is simple and easy within Swarmia.

  1. Ensure that you have created the 'Parent' team(s) in your team structure.
    1. This parent team will inherit the membership of the later assigned subteams, but in order to first establish the parent team, you will need to add at least one member. 
  2. Create desired subteams, and map them to the appropriate Parent Team.
    1. Depending on your organizational structure, you might need to repeat the same process multiple times (for different levels of your organization).

You don't need to create a team to resemble your entire engineering organization. You can automatically use the organization level, even if you don't create any hierarchy of teams.


Teams with subteams

  • For the most part, teams with subteams work just like other Swarmia teams. No additional configuration is required.
    • For teams with subteams, the work shown everywhere across Swarmia is defined as a combination of their subteams’ work.
    • You can add working agreements and enable notifications for teams on all levels.
    • You can add direct members or GitHub teams or to any team, even if the team has subteams.


  • Each team can only have one parent team. This means you can't use team hierarchy to map a matrix organization structure. Please contact Swarmia support via the in-app chat if you would have a need for such a configuration.
  • If you convert a team to a parent team, it loses any filters around team ownership it previously had — they will be inherited from the subteams instead.

Refining Team Ownership

Teams are important for managing which pull requests (PRs) and issues are included in the data for different Swarmia features, from insights to working agreements. You'll want to ensure that the Pull Request and Issue Ownership of your team is correct to ensure the most accurate metrics. 

  1. Team Pull Request Ownership
    1. By default, we include any PRs created by anyone in the team. You can configure PR ownership rules for teams to adjust which work is included by navigating to the Team Pull Request page.
  2. Team Issue Ownership
    1. To unlock Issue data in Swarmia in the Work Log view and Flow Insights, you will first need to assign Team Issue Ownership in Settings → Team → Issues.
    2. Once a team has been properly mapped, they will show up as 'assigned' in the Team Management page.

Screenshot 2023-07-14 at 1.32.24 PM

Team Notifications

Enabling Team Notifications in Slack allows your team to be updated on things like important Pull Request and Issue activity as well as Working Agreements. You can enable these for your teams in Settings → Team → Notifications

Adopting Team Working Agreements

Working Agreements help teams continuously improve with clear goals and consistent execution. 

We believe in self-organizing teams that own their ways of working. With Swarmia’s Pull Request DashboardWork Log and Insights, you already get full visibility into your process and can identify potential improvements — but transparency alone is not enough to become better and stronger as a team.

Swarmia's Working Agreements help you spring from idea to action, execute consistently and form new habits as a team.

Screenshot 2023-07-14 at 1.54.46 PM

Ready to jump in? Why not have a conversation with your team about issues you’ve detected about team focus or Pull Request cycle times, and head over to the Working Agreements area in the app to get started!

After choosing what to improve and setting up the Working Agreement, you get insights about how you’re doing as well as a list of all exceptions from the past two weeks helping you pinpoint specific issues or discussions to have with the team.