Team Setup Best Practices

Teams are the primary organizational unit in Koalr. Every metric -- DORA, flow, deploy risk, coverage -- can be filtered by team, and the team comparison dashboard lets engineering leaders identify which teams are thriving and which need support.

This guide covers how to create teams, import them from existing tools, configure ownership rules, and use team-scoped dashboards effectively.

Time to complete: 10--15 minutes per team.

---

How teams work in Koalr

A Koalr team is a named group of members that owns specific repositories, file paths, or code areas. When you filter any dashboard by team, Koalr scopes the metrics to work authored or reviewed by that team's members.

Teams have:

• Members with roles (Lead or Member).
• Ownership rules that control which PRs and issues are attributed to the team.
• Settings including timezone, color, description, and parent team (for hierarchy).
• Working agreements -- documented team standards for review time, PR size, etc.

---

Step 1: Create your first team

1. Navigate to Teams in the left sidebar.
2. Click + Create Team in the top-right corner.
3. Fill in the team details:
   • Team Name (required) -- e.g., "Platform Engineering" or "Payments Squad."
   • Description (optional) -- what the team works on.
   • Timezone -- used for deployment timing analysis and report scheduling.
4. Click Create Team.

You will be redirected to the team detail page where you can add members.

---

Step 2: Import teams from GitHub (recommended)

If your GitHub organization already has teams defined, import them directly instead of creating them manually:

1. On the Teams page, click the Import Teams button.
2. A modal shows your connected integration sources (GitHub, Jira, Linear).
3. Select GitHub and choose which GitHub teams to import.
4. Koalr matches team members by GitHub login and creates teams with the correct membership.

This saves time and keeps your Koalr teams aligned with your GitHub organization structure. After importing, you can rename teams, adjust membership, and configure additional settings.

---

Step 3: Add and manage team members

From the team detail page, click Settings then select the Members tab:

1. Click Add member to open the member selector.
2. Choose from your organization's active members (shown with name and email).
3. Assign a role:
   • Lead -- can update team settings, manage membership, approve working agreements, and view all team metrics including individual developer data.
   • Member -- can view all team dashboards and metrics. Cannot modify team configuration or member lists.
4. Click Add.

Members must already have active seats in your Koalr organization. If someone is missing from the list, invite them first at Settings then Members.

---

Step 4: Configure ownership rules

Ownership rules determine which pull requests and issues are attributed to a team for metric calculation. Without rules, attribution is based solely on the author's team membership.

From the team settings page, select the Ownership tab:

1. Click + Add rule.
2. Configure the rule:
   • Resource -- Pull Requests or Issues.
   • Match field -- what to match against:
     • Repository name -- match PRs from repos matching a glob (e.g., backend-*).
     • Label -- match issues/PRs with a specific label (e.g., team:platform).
     • File path -- match PRs touching files matching a glob (e.g., src/payments/**).
     • Author login -- match by PR author.
     • Title -- match by PR/issue title pattern.
   • Pattern -- the glob or text pattern to match.
   • Owner field -- which user on the PR/issue to use for attribution (Author, Assignee, or Reviewer).
   • Priority -- rules are evaluated in priority order; the first match wins.
3. Click Create rule.

Example ownership rules

Team	Rule	Purpose
Payments	Repository matches billing-*	All billing repos belong to Payments
Platform	File path matches infra/**	Infrastructure code is Platform's
Mobile	Label matches team:mobile	Labeled issues go to Mobile

If no rule matches a PR, it is attributed based on the author's team membership.

---

Step 5: Set up team hierarchy (optional)

If your organization has a multi-level structure (e.g., a "Backend" group containing "Payments" and "Platform" squads), you can set parent teams:

1. Go to the team's Settings page.
2. Under Team Hierarchy, select a parent team from the dropdown.
3. Click Save changes.

Metrics roll up from child teams to parent teams, giving engineering directors a view across their entire organization.

---

Step 6: Use the team comparison dashboard

The Teams page shows all teams in a sortable comparison table with key metrics:

Column	What it shows
Cycle Time P50	Median time from PR open to merge
Deploy Frequency	Deployments per day
PRs Merged	Total merged PRs in the period
Avg Review Time	Median time to first review
Open PRs	Currently open pull requests

The table is sorted by cycle time (fastest first) by default. Use the period selector (7, 14, 30, or 90 days) to adjust the time window.

Color coding helps you spot issues at a glance:

• Green -- cycle time 4 hours or less, review time 4 hours or less.
• Amber -- cycle time 4--24 hours, review time 4--12 hours.
• Red -- exceeds targets.

Summary tiles

Above the table, four summary tiles show organization-level aggregates:

• Total teams.
• Total members across all teams.
• Teams with 4-hour or less cycle time (high performers).
• Open PRs org-wide.

---

Step 7: Drill into a team

Click View on any team row to see the team detail page with:

• DORA Performance tier -- an overall tier badge (Elite, High, Medium, Low) with links to the full DORA and Flow dashboards filtered for that team.
• DORA Metrics grid -- Deploy Frequency, Lead Time P50, Change Failure Rate, and MTTR for the team.
• Pull Request Health grid -- Cycle Time P50, Time to First Review, PRs Merged, and Aging PRs (open longer than 7 days).
• Members table -- all team members with their individual contribution data.
• Working Agreements -- documented team standards that can be tracked and scored.

---

Best practices for team structure

Match your team topology

Create teams that mirror how your organization actually ships software. Common patterns:

• Squad-based -- one Koalr team per cross-functional squad (e.g., "Search Squad," "Growth Squad").
• Platform + product -- separate teams for platform/infrastructure and product feature squads.
• By service -- one team per microservice or bounded context.

Keep teams to 5--12 members

Teams smaller than 5 have too little data for meaningful metrics. Teams larger than 12 dilute individual accountability. If a team has 20+ members, consider splitting into sub-teams with a parent team for aggregation.

Use ownership rules over manual attribution

Ownership rules ensure consistent attribution as team membership changes. A rule like "all PRs touching src/billing/** belong to Payments" continues working even when new engineers join the team.

Review team metrics weekly

Use the team comparison table in your weekly engineering sync to identify teams with rising cycle times, growing PR queues, or declining deployment frequency. Early intervention prevents small problems from becoming large ones.

---

What to do next

• Set DORA goals per team using the goal panel on the DORA dashboard. See DORA Metrics Setup.
• Configure team notification channels at Teams then Settings then Notifications to send team-specific alerts to dedicated Slack channels.
• Set up weekly reports scoped to each team. See Weekly Engineering Report Guide.
• For the full reference on roles and permissions, see Teams & Members.