Configure Swarmia and get up and running with your team
Data-Driven Superpowers for 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
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 Issue Types and Workflows
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.
How Swarmia Deals with Work
While your issue tracker is probably configured with a variety of issues and workflows, Swarmia is focused on giving you the facts about your flow. We cut through the complexity in your issue tracker and divide work into four simple categories:
Epic: Large undertakings such as projects from the roadmap that usually span long timeframes and involve multiple teams
Story: Smaller bodies of work that usually add direct customer value and are important for the team to track on a daily basis
Task: Planned technical or administrative work that doesn’t add direct customer value, but is still important for the team to plan and deliver
Bug: Usually unplanned work that results from production defects or other unexpected outcomes that must be addressed and tracked
Swarmia’s issue workflow is similarly simple and consists of three statuses:
To Do: Issues that may be planned or specified, but not expected to be worked on by your team just yet
In Progress: Issues that your team is expected to be working on at the moment, even if they are currently blocked or otherwise inactive
Done: Issues that are completed, closed, or canceled and that are not expected to be worked on anymore by your team
To map your Jira workflow, navigate to the Organization tab under Jira Settings. For each Swarmia status (To Do, In Progress, Done), select all the corresponding columns from your Jira. If you use Jira fields to assign issues to teams, or to assign issues to Epics, you can also configure them here.
💁♀️ Workflow mapping applies to the whole organization. If other teams in your organization are already using Swarmia, make sure that you don’t remove existing mappings. Simply check if any Jira columns from your workflow are missing and add them. Issue mapping is team specific.
To map Jira issues to Swarmia’s issues, navigate to the Teams tab under Jira Settings, find your team, and click Assign (if some mapping already exists, click Edit).
For each type of work you are interested in (Epic, Story, Task, Bug), click the respective plus-button and create a mapping: Select one or more Jira projects and issue types, and optionally a Team Id that reflects the Jira issues you expect to see for this type of work. After configuring all the mappings you need, hit Save and you’re all set.
💁♀️ Mapping subtasks is not necessary. Swarmia recognizes Jira hierarchies, so mapping subtasks is often unnecessary. For example, mapping a Pull Request to a Jira subtask means that it is also automatically mapped to its parent Story, Task and/or Epic in Swarmia.
To verify that the mapping is working, head over to Flow Insights and check that you can see data about work in progress and cycle time for each issue type you’ve just mapped.
If you are already linking Pull Requests to Jira issues, you should see data in Work Log as well.
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.
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 firstname.lastname@example.org.