Team Setup

Configure Swarmia and get up and running with your team

Swarmia is a tool for teams. By integrating with your issue tracker and version control, we reveal hidden patterns about your focus and workflow to help you work better together. This guide helps your team get started with Swarmia.

In a nutshell

Setting up is easy but requires some thinking and discussion as a team to ensure that your data is correct and that nobody gets caught by surprise.

Here are the steps in a nutshell, and the expected results:

  • Check your GitHub team setup → Contributor Settings should show all your team members, and nobody else

  • Map the issues the team owns → Flow Insights and Work Log will show data for the issues that belong to the team

  • Schedule a Slack digest → The team will receive a daily summary of their work in the chosen Slack channel, at the chosen time

  • Invite your team to Swarmia → Contributor Settings will show a Swarmia check mark under your team members’ names as they join

Now, let’s walk through the steps in a bit more detail.

Set up team memberships

To get good data from Swarmia, it’s crucial to get your team memberships right. Among other things, Pull Requests are assigned to teams based on what teams their creators and reviewers belong to, which lets teams see all Pull Requests that are relevant to them in a simple real-time dashboard.

The Pull Requests view is a dashboard for the team

 

Swarmia gets information about team membership from GitHub. It’s common to include extra members in GitHub teams for repository access control, or to exclude members if they aren’t expected to contribute to the codebase. Some team members may not have GitHub accounts at all. You can keep all your existing access control setups, but make sure that there’s a team in GitHub that includes everyone in your actual team, and nobody else.

💁‍♀️ Configure code owners. We love it when teams take shared responsibility for their codebase, and when everyone has the opportunity to review each other’s contributions. A great way to do this automatically is by defining a team as the code owner in GitHub. Check the GitHub doc about code owners here.

When your GitHub setup is right, this should be reflected in Contributor settings. Check that all your team members, and only your team members, are displayed when you select your team from the dropdown menu. Also check that there are no duplicate identities. If there are duplicates, you can merge them by ticking their boxes and hitting the Merge button.

Map issues that belong to the team

Your issue tracker tells you what was planned or expected, while your version control tells you what actually happened. Swarmia helps you connect the dots by linking Pull Requests to issues, and visualizing the relationship between the two on a timeline we call Work Log.

In order to take benefit of this feature, you'll need to connect and configure the Jira integration. If this has already been done for the organization, you only need to map the team ownership to tell which issues interest your team.

Work Log connects issues from your tracker with activity from your version control

Connect to Slack

Lots of apps are competing for your attention on Slack, and we don’t blame teams who banish noisy apps to their own channels never to look at them again. We hate spam as much as you do, so in addition to judicious notifications when an action is expected, Swarmia sends exactly one message to the team per day.

💁‍♀️ Remember to talk with the team. Don’t forget to talk with your team and get everyone’s opinion before setting up the daily Slack digest. Sudden broadcasts about all the work that’s going on can feel disruptive if they start arriving on the team’s channel without explanation.

The daily Slack digest is a summary of relevant Pull Requests, issues and Working Agreements. Use it as a conversation starter for your daily standup, or just a reminder to help you keep track of open topics and stick to new Working Agreements.

The daily Slack digest is a summary of relevant topics for the team

To set up the daily Slack digest for your team, go to Slack Settings, find your team, and schedule the digest. If you’re doing daily standup meetings with the team, try scheduling the digest to a few minutes before the meeting.

Invite Team Members

It’s not necessary for developers to start using yet another web app that disrupts their workflow. Most day-to-day interaction with Swarmia such as staying on top of Pull Requests and Working Agreements happens over Slack. However, to get personal Slack notifications when something is expected of you, you need to create a personal Swarmia account and connect Slack.

 

Swarmia sends you direct messages on Slack only if something is expected of you

To invite your team members, just copy the invitation link either from the front page of Swarmia or from Organization Settings and share it with your team. If they have access to your GitHub organization, the link lets them access the tool and create an account.

If some team members already have accounts, but have not connected Slack, they can do so by navigating to Personal Settings and clicking on Integrate Slack.

Continuous Improvement with Swarmia

Managing Pull Requests

Lack of visibility is a common reason why Pull Requests are stuck in a queue or just forgotten. The first thing we recommend is to start regularly checking the Pull Requests view, where it’s easy to spot problematic Pull Requests and get a clear picture of the team’s throughput. Going a bit further, it’s a great idea to get into the habit of quick code reviews with a Working Agreement. You can read more about reviewing Pull Requests faster with Swarmia in our case study.

In the Pull Requests view, you can also manually link Pull Requests to issues. Linking Pull Requests to issues is another habit worth getting into, as it enables Swarmia to reveal hidden patterns about your focus and workflow in Work Log.

💁‍♀️ Linking Pull Requests to issues. You don’t need to visit Swarmia to link Pull Requests to issues. It’s enough to include the issue key in the Pull Request title (e.g. Foobar [DEV-123]) or start the GitHub Branch name with the issue key (e.g. DEV-123-foobar). And if you merge an unlinked Pull Request, Swarmia will send you a message on Slack where you can select an issue from a dropdown.

Retrospectives with Swarmia

Getting into the habit of discussing Pull Requests and analyzing why some get stuck is a great way to embark on the journey of continuous improvement. Systematically analyzing exceptions to Pull Requests and other Working Agreements will reveal new areas of improvement that you can address as a team.

Are you working on too many things at once? Are you working and learning effectively as a team? As long as you’re linking Pull Requests to issues, reviewing the Work Log in retrospective meetings will reveal any issues with focus, siloing and flow that you may be experiencing, among other important patterns.

Are your builds fast and reliable so developers can create small Pull Requests that are easy to review and merge with confidence? Continuous Integration Insights will help you understand and prioritize possible issues with the build pipeline.

💁‍♀️ Make it a Habit. To drive continuous improvement systematically as a team, consider getting into the habit of analyzing exceptions to Working Agreements and patterns in Work Log in your team retrospective meetings.

Get in Touch

Do you have any questions or comments about using Swarmia? Is something missing, or can we do something differently to better support your team? Don’t hesitate to reach out on Intercom or Slack, or just email us at hello@swarmia.com.