Skip to content
Componecat Docs

Team sync

Every entity in the catalog has an owning team. Team sync keeps those teams honest: instead of maintaining a second copy of your org chart inside Componecat, you point an integration at the system that already knows it — GitHub, GitLab, Atlassian, or Microsoft 365 — and Componecat mirrors the teams and their membership on a schedule.

Team sync is a capability on an integration; see Integrations for connecting one.

What each provider syncs

Section titled “What each provider syncs”
Provider Becomes a team Members come from Credential needs
GitHub Each team in one GitHub organization The team’s members read:org. Adding user:email lets Componecat match members by email.
GitLab Each group and subgroup the credential can see, or one group subtree The group’s direct (non-inherited) members read_api (or api)
Atlassian Each team in the Atlassian organization The team’s members, with the name, picture, and (where the profile shows it) email from their Jira profile An API token for a user who can read the organization’s teams and browse users on the site
Microsoft Your choice of Team Source: each Microsoft 365 group (the type behind Microsoft Teams, and the default), each security group, or each department on user profiles For groups, the group’s direct user members, with nested groups and service principals excluded. For departments, the enabled, non-guest users with that department An admin-consented application permission: Group.Read.All (or GroupMember.Read.All) for groups, User.Read.All for departments

Enable and configure

Section titled “Enable and configure”

Open the integration and find the Team Syncing card. Configure it before switching it on — the panel is editable while the capability is off.

Setting Meaning
Schedule (cron) How often the sync runs. Default 0 */6 * * * — every six hours.
Team Source Microsoft only. What becomes a team: Microsoft 365 groups (the default), Security groups, or User departments. See Teams from Microsoft.
Group Filter Microsoft only, and called Department Filter for the departments source. A name prefix, such as Team-. Only groups (or departments) whose name starts with it are read from Microsoft, which keeps a sync fast in a large tenant. Microsoft may match it case-sensitively, so use the same capitalization as the names. Blank reads everything of the chosen source.
Team Name Filter Optional regular expression. Only teams whose whole name matches are synced; blank syncs everything. Try Platform-.* or Team-(Alpha|Beta). Add a group called name to keep just part of the name: Team-(?<name>.+) syncs “Team-Payments” as Payments.
GitHub Organization GitHub only, and required. The organization login whose teams are synced — one organization per integration.
GitLab Group GitLab only. A group id or full path such as acme-corp/engineering, scoping the sync to that group and its subgroups. Blank syncs every group the credential can see.

The Group Filter is applied first, by Microsoft, and the Team Name Filter then runs on what comes back. Use both together: Team- as the Group Filter and Team-(?<name>.+) as the Team Name Filter reads only the Team- groups and names each team without the prefix.

When the Team Name Filter shortens names, two upstream teams can end up with the same one — Team-Payments and Squad-Payments both become Payments with (Team|Squad)-(?<name>.+). The first is synced and the second is reported as a name conflict in the sync history. If a group’s name part comes out empty, it keeps its full name. Teams that were already synced are renamed in place, so their ownership and membership stay attached.

An invalid regular expression is rejected when you save, so a typo can’t quietly drop every team from the next run — and a GitHub integration won’t let you enable team syncing until you’ve named the organization, since a sync without one has nothing to read.

Use Run now for an immediate sync — worth doing after the first configuration so you can check the results before the schedule takes over.

Teams from Microsoft

Section titled “Teams from Microsoft”

The Team Source setting decides what a Microsoft team is.

  • Microsoft 365 groups syncs the groups behind Microsoft Teams, Outlook groups and SharePoint team sites.
  • Security groups syncs security groups instead, including dynamic and mail-enabled ones. Distribution lists are never synced. Only a group’s direct user members are synced: a security group whose members are other groups syncs as an empty team.
  • User departments makes one team per Department value on your users’ profiles, with the users who have it as members. Guests and disabled accounts are left out. Departments that differ only in capitalization or spacing, such as Engineering and engineering , become one team, named by the most common spelling.

A department has no id of its own in Microsoft, so its name is its identity. Renaming a department in Microsoft removes the old team and creates a new one on the next sync.

Changing the Team Source on an integration that has already synced replaces its teams with the new source’s. A team whose name stays the same across the switch, such as a Platform group followed by a Platform department, is kept and re-linked, so its entity ownership carries over. Teams with no same-named counterpart are removed.

Test connection checks both permissions and says which sources the app registration can serve.

Members without a Componecat account

Section titled “Members without a Componecat account”

A team member doesn’t need an account here. Everyone the provider reports lands on the roster, whether or not they’ve ever signed in, so a synced team shows its real size instead of only the handful of people who happen to have logged in.

Members with no account are marked No account on the team page. They are there for ownership and contact only — they can’t sign in, and being on a team grants nobody any access.

You can also record someone by hand: on a team you own, Add Member takes a name and email for a person with no account, alongside the picker for existing users.

How members are linked to users

Section titled “How members are linked to users”

Componecat matches each member to a user in your organization by email first, and by the provider’s user identity as a fallback. A match links the two, and the user’s own name and picture then take over on the roster.

A member who matches nobody stays on the roster, unlinked. They link themselves once an account with their email turns up — the next sync picks it up, and an hourly background pass catches teams that aren’t syncing.

Whether emails are available depends on the provider and the credential: GitHub exposes member emails only when the token carries user:email and the member’s visibility allows it, and GitLab exposes them only to credentials permitted to see them. Atlassian’s team roster carries only account ids, so Componecat looks each one up in Jira for the person’s name and picture; an email comes along only when their profile makes it visible, and otherwise matching falls back to looking up your users’ emails in Jira. Microsoft falls back to the user principal name when a mailbox address isn’t set. A member the provider gives no email for is still recorded — they simply can’t be linked automatically.

What a sync does to your teams

Section titled “What a sync does to your teams”
  • New upstream teams are created and tagged as managed by that provider.
  • An existing Componecat team with the same name that nobody else manages is adopted — it keeps its identity, its entity ownership, and its history, and becomes managed from then on. So is a team this integration synced earlier whose upstream original no longer exists, such as a team deleted and recreated upstream under the same name. A team already managed by a different source is left alone, and the collision is recorded as an error on the run.
  • Renames upstream are applied, unless the new name is already taken by another team locally, in which case the old name is kept.
  • Teams that disappear upstream are removed from Componecat on the next run.
  • Membership is added and removed to match the upstream team exactly, including people with no Componecat account.

Managed teams show a badge with the source and a link out to where they’re managed, and they can’t be edited inside Componecat — name, description, and membership all come from upstream. The REST API and the MCP team tools report a managed team’s source and its id in that system (for Atlassian, the team id), so automation can address the same team upstream. Teams you create by hand are unaffected by sync unless the adoption rule above picks them up.

Reading sync history

Section titled “Reading sync history”

While the capability is enabled, the card lists recent runs with teams created, updated, and removed, membership changes, and errors. Errors are per team, so one team that fails — a name collision, an upstream permission problem — doesn’t stop the rest of the run.

Troubleshooting

Section titled “Troubleshooting”
  • A GitHub sync fails with “missing a TeamSync organization”. The capability has no GitHub Organization set — open the Team Syncing card, choose Edit Configuration, and enter the organization login.
  • You need teams from a second GitHub organization. One integration syncs one organization, and connections are unique per provider and base URL — so a second GitHub.com connection isn’t possible. Sync the organization that owns your catalog entities, and add the rest of the teams by hand.
  • Synced members show as “No account”. That’s expected for anyone who hasn’t signed into Componecat. They stay on the roster and link to their account automatically once it exists. If everyone shows this way and you expected matches, the credential probably can’t see member emails.
  • Teams sync but they’re empty. The upstream teams really have no members the credential can see. Check that the token can read team membership for the organization.
  • Too many teams appeared. GitLab syncs every visible group and subgroup — set GitLab Group to scope it, or use the team name filter.
  • Atlassian teams are missing. Org-scoped teams sync by default; site-scoped teams need the Site ID set on the connection.
  • Atlassian members show as account ids. Names and pictures come from Jira, which needs the Site ID set and a credential that can browse users on that site. Members that can’t be looked up keep their account id until a later sync resolves them.
  • Microsoft groups are missing. Check that the Team Source matches the kind of group you use: security groups aren’t read by the default Microsoft 365 groups source, and distribution lists are never read. Then check that the app registration has admin-consented Group.Read.All, and that the Group Filter, if set, is a prefix of the missing groups’ names, in the same capitalization.
  • Microsoft department sync fails with a 403. The departments source reads users, which needs the User.Read.All application permission with admin consent. Test connection tells you whether it’s granted.
  • Microsoft sync is slow or stops short. A run syncs at most 5,000 teams. In a large tenant, set the Group Filter (or Department Filter) so only the teams you want are read.
  • A run failed outright. Use Test connection on the integration to separate a credential problem from a configuration one.
Section titled “Related”