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

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