# Teams

Heeler automatically organizes your repositories into teams by syncing with your existing team structures in GitHub, GitLab, or Port.io. Instead of manually assigning repositories to teams, Heeler reads your organizational hierarchy and mirrors it — keeping team ownership accurate and up to date as your organization evolves.

## Why Configure Team Mapping?

* **Accurate ownership**: Every repository is automatically assigned to the correct team based on your source of truth
* **Faster onboarding**: New repositories are assigned to teams without manual intervention
* **Consistent access**: Team membership drives repository access and security visibility in Heeler
* **Reduced drift**: As teams restructure, Heeler stays in sync with your organization

## Supported Sources

| Source      | How Teams Are Derived                                    |
| ----------- | -------------------------------------------------------- |
| **GitHub**  | GitHub Teams linked to repositories                      |
| **GitLab**  | GitLab Groups (by group name or path prefix)             |
| **Port.io** | Port.io team entities linked to software catalog entries |
| **Heeler**  | Manual team creation (no external sync)                  |

## Prerequisites

* An active connection to your source platform (GitHub, GitLab, or Port.io) configured under **Administration > Connections**
* Organization owner or admin permissions to view team/group structures in your source platform

## Selecting a Team Source

1. Navigate to **Administration > Connection Mapping > Teams**
2. Click the **Source** badge in the table header to open the source selector
3. Select your desired source (GitHub, GitLab, Port.io, or Heeler)

{% hint style="warning" %}
Switching sources will stop auto-creating teams from the previous source. Existing teams remain but will no longer be updated. A confirmation dialog will appear before the switch takes effect.
{% endhint %}

4. Once a source is selected, Heeler immediately queues a sync job. Teams will begin appearing within a few minutes.

## Configuring the Mapping

For sources other than Heeler, click **Configure Mapping** in the toolbar to customize how teams are created.

### GitHub Teams

* **Grouping Key**: Select the field used to identify teams (e.g., `team_name`, `team_slug`, or a custom property)
* **Allowed Values**: Optionally restrict which teams are synced. Leave empty to include all teams.

### GitLab Groups

* **Grouping Key**: Choose `group_path` for path-prefix matching or `group_name` for direct group name mapping
* **Allowed Values**: Select specific groups to include (e.g., only `org/engineering`, `org/platform`)

{% hint style="info" %}
GitLab path-prefix matching uses longest-prefix-first logic. A repository at `org/platform/auth-service` matches `org/platform` before `org`.
{% endhint %}

### Port.io Teams

* **Blueprint**: Select the blueprint that represents teams in your Port.io catalog
* **Attribute Mapping**: Map Port.io properties to Heeler team fields (Name, Slack Channel, Portfolio, Domain)

### Attribute Mapping Table

For all sources, the attribute mapping table lets you define how source fields correspond to Heeler team properties:

| Column               | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| **Team Field**       | The Heeler property to populate (e.g., Name, Slack Channel)              |
| **Source Attribute** | The field from your source platform (auto-populated from harvested data) |
| **Supported Values** | Optionally restrict which values are accepted for this field             |

Click **+ Add Attribute Mapping** to map additional fields beyond the defaults.

## Previewing Results

Before saving, click **Preview Mapping Results** to see a dry-run of what teams would be created, including the number of repositories each team would own. This helps verify your configuration before it takes effect.

## Creating Teams Manually

Regardless of the selected source, you can always create teams manually by clicking **Create Team** in the toolbar. Manual teams coexist with auto-synced teams.

## How Syncing Works

* Team sync runs automatically every **4 hours** and immediately when you save a new configuration
* New teams are created, orphaned teams are removed, and repository assignments are updated
* Team membership (users) is managed separately and is not affected by source changes
* Repository access is recalculated after each sync based on current team-repository assignments