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, matched to Atlassian accounts by email An API token for a user who can read the organization’s teams
Microsoft Each Microsoft 365 group — the type behind Microsoft Teams The group’s user members; nested groups and service principals are excluded The Group.Read.All (or GroupMember.Read.All) application permission, admin-consented

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 Name Filter Optional regular expression. Only teams whose name matches are synced; blank syncs everything. Try Platform-.* or Team-(Alpha|Beta).
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.

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.

How members are matched

Section titled “How members are matched”

Componecat matches each upstream member to a user in your organization, by email first and by the provider’s user identity as a fallback. Upstream members with no matching Componecat user are skipped — typically people who haven’t signed in yet. They join the team automatically once they have an account and the next sync runs.

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 resolves members through an account lookup by email, and Microsoft falls back to the user principal name when a mailbox address isn’t set.

Memberships are removed only for users the run could resolve, so a temporary lookup failure never empties a team.

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. 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.

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. 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.
  • Teams sync but they’re empty. Members are matched to Componecat users. If nobody matched, the credential probably can’t see member emails, or those people don’t have accounts in your organization yet.
  • 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.
  • Microsoft groups are missing. Only Microsoft 365 groups are synced — security groups and distribution lists aren’t. Check that the app registration has admin-consented Group.Read.All.
  • A run failed outright. Use Test connection on the integration to separate a credential problem from a configuration one.
Section titled “Related”