> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/set-up/teams/team-mapping.md). # Team Mapping Team Mapping tells Hivel which team owns which repositories and which incident services. Hivel uses these mappings to attribute deployments, incidents and related metrics to the right team, so team dashboards and insights reflect the right data. #### Before You Start * **Teams**: Team Mapping lists the teams that already exist in Hivel. Create your teams first on the **Teams** page. * **Integrations**: Each column on the page depends on an integration. If neither is connected, Team Mapping does not appear in the Settings menu. | Column | Integration required | What you map | | ----------------- | -------------------- | ------------------------------------------- | | Repos | Deployment API | Your organization's repositories. | | Incident Services | Incident API | Services that incidents are raised against. | * **Permissions**: **View Team Mapping Menu** lets you see the mappings. **Modify Team Mapping** lets you change them. Ask your Hivel admin if you need access. ## Why Mapping Is Needed A deployment tells Hivel which repository was deployed, and an incident tells Hivel which service was affected. Mapping a repository or service to a team connects that data to the team, so metrics such as deployment frequency, change failure rate and time to recovery are reported for the right team. One repository or service can be mapped to more than one team, and one team can have many repositories and services. ### **What are incident services?** An incident service is a service that incidents are raised against, such as "Checkout API" or "Payments DB". Every incident is tied to a service in your incident management tool. Hivel reads the list of services from your connected incident tool, so you do not create them in Hivel. ## What the Page Shows **Application:** Hivel Platform 1. Go to **Settings**. 2. Select **Team Mapping**.

The page contains the following. | Item | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Unassigned summary | A message at the top, such as "48 repos and 16 incident services aren't mapped to any team yet." It disappears once everything is mapped. Users with edit access also see a **View unassigned** button here. | | Team column | One row for each team. | | Repos and Incident Services columns | The repositories and services mapped to each team. The first two are shown, and **+N** shows how many more there are. Hover over **+N** to see their names. | When nothing has been mapped yet, every cell reads "No repos mapped" or "No services mapped". Nothing is mapped automatically, so you add the mappings yourself. ## How to Map Items to Teams ### Method 1: Map Repos or Services for One Team **Step 1: Open the editor** **Application:** Hivel Platform 1. Hover over the team's row and select the pencil icon in the **Repos** or **Incident Services** cell.

If the pencil icon is grey and a tooltip says you do not have permission, you have view access only. Ask your admin for **Modify Team Mapping**. **Step 2: Select the items** **Application:** Hivel Platform 1. Search for an item in the search box. 2. Tick each item that belongs to the team. Untick any item that no longer belongs.

**Step 3: Save** **Application:** Hivel Platform 1. Select **Save**. The button is enabled only after you change something. **Success:** A message such as "Repos for Payments saved" appears and the cell shows the new items. **Failure:** The message "Could not save team mapping, please try again" appears. Select **Save** again. ### Method 2: Assign Unassigned Items in Bulk **Step 1: Open the unassigned list** **Application:** Hivel Platform 1. Go to **Settings** > **Team Mapping**. 2. In the summary at the top, select **View unassigned**.

The **Unassigned items** window opens on the tab with more items left to assign. Use the **Repos** and **Incident Services** tabs to switch. **Step 2: Select the items** **Application:** Hivel Platform 1. Search for items using the search box. 2. Tick the items you want to assign, or tick **Select all** to select every item on the current page.

**Step 3: Choose the teams** **Application:** Hivel Platform 1. Select **Team** at the top of the window.

2. Tick one or more teams. The selected items are assigned to every team you tick. **Step 4: Save** **Application:** Hivel Platform 1. Select **Save Changes**. The button is enabled only after you select at least one item and one team. 2. Review the confirmation, such as "3 repos will be assigned to Growth and Payments", and select **Save**. **Success:** A message such as "Assigned 3 repos to 2 teams" appears and the window closes. **Failure:** The message "Unable to save changes, please try again" appears. Select **Save Changes** again. ## Troubleshooting | Problem | Likely cause and fix | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Team Mapping is missing from the Settings menu | Neither the Deployment API nor the Incident API is connected, or your role does not include a Team Mapping permission. Connect an integration in **Settings** > **Integrations**, or ask your admin. | | An incident service is not listed | Your incident tool has not synced yet. Wait for the sync and try again. | | The **View unassigned** button is missing | Either every item is already mapped, or you have view access only. |