Skip to content
Componecat Docs

Integrations

An integration is a single authenticated connection to one upstream system — your GitHub organization, your GitLab instance, your Atlassian site, your Microsoft 365 tenant. On top of that one connection you switch on capabilities: the individual jobs that keep the catalog in step with reality.

That split matters in practice. You store one credential for GitHub, and the same connection can scan repositories for descriptors, import your teams, and pull documentation — three capabilities, one credential to rotate.

Where integrations live

Section titled “Where integrations live”

Integrations are organization-scoped and admin-only. Open the organization switcher, choose Organization settings, and pick the Integrations tab. From there you can add a connection, open one to configure its capabilities, or remove one.

The tab appears when your plan includes integrations. If a plan change removes them, existing connections stay visible and can still be tested or deleted, but their capabilities stop running and can’t be reconfigured until the feature is available again.

What each provider can do

Section titled “What each provider can do”
Provider Repository scanning Team sync Documentation sync
GitHub yes yes yes
GitLab yes yes yes
Bitbucket yes — yes
Atlassian — yes —
Microsoft — yes —

Each capability has its own guide:

  • Repository scanning — discover and ingest componecat.yaml descriptors, and keep linked repository metadata fresh.
  • Team sync — import teams and their membership so entities have real owners.
  • Documentation sync — pull Markdown from repositories into entity documentation.

Connect a provider

Section titled “Connect a provider”
  1. Go to Organization settings → Integrations and choose Add integration.
  2. Pick the provider you’re connecting.
  3. Fill in the connection form and submit. The connection is created immediately; no capability runs until you enable one.
  4. On the integration’s page, choose Test connection to verify the credential. The list page shows when each connection was last verified.

What the form asks for depends on the provider:

Provider Authentication Base URL Other fields
GitHub Personal access token, or a GitHub App private key / installation token https://github.com, or your GitHub Enterprise web root —
GitLab Personal access token, or a project access token https://gitlab.com, or your self-managed instance —
Bitbucket Access token https://bitbucket.org —
Atlassian Basic (API user email + API token) or Bearer (scoped API token) https://api.atlassian.com Atlassian Org ID (required), Site ID (only for site-scoped teams)
Microsoft Entra client credentials — tenant ID, client ID, client secret https://graph.microsoft.com/v1.0 Authority override, for sovereign clouds such as Azure Government

Give the credential the least access that covers the capabilities you plan to enable; the per-capability guides list what each one needs.

One connection per system

Section titled “One connection per system”

Within an organization, a provider is identified by its kind and base URL — so one GitHub.com connection, one Bitbucket Cloud connection, and as many self-hosted GitLab or GitHub Enterprise connections as you have instances. Atlassian is the exception: connections are distinguished by Atlassian Org ID, so several Atlassian organizations can share api.atlassian.com.

A single Git connection reaches every organization, group, or workspace its credential can see — you scope what gets scanned in the capability’s settings rather than by adding more connections.

Enable a capability

Section titled “Enable a capability”

Open an integration and you’ll see a card per capability the provider supports. Each card carries a toggle, and below it a configuration panel you can edit before you turn the capability on, so the first run uses the settings you want.

Every capability shares the same three controls:

  • Schedule — a cron expression for recurring runs. The default, 0 */6 * * *, runs every six hours. Clear thinking about frequency pays off: repository scans and team syncs both call rate-limited upstream APIs.
  • Run now — queues a single run immediately, independent of the schedule. Useful right after you change settings.
  • History — the last runs with their status, counts, and per-item errors. A run in progress refreshes on its own.

Disabling a capability removes its schedule. Its history is kept, and the settings you entered are still there when you re-enable it.

Credentials and secrets

Section titled “Credentials and secrets”

Credentials are encrypted before they’re stored and are never shown back to you. To rotate one, edit the integration and enter the new value — leaving the credential field blank keeps the existing one, so you can change a name or base URL without re-entering the secret.

Git connections also have a webhook secret, used to authenticate the push notifications your Git provider sends. It’s generated on demand and shown once — see Repository scanning.

Remove an integration

Section titled “Remove an integration”

Delete on the integration page removes the connection, its capabilities, their schedules, and their run history. What those capabilities produced stays put: entities ingested from descriptors, teams imported by team sync, and documentation already pulled from Git all remain in the catalog. They simply stop being updated.

Troubleshooting

Section titled “Troubleshooting”
  • A credential problem. Start with Test connection — it reports the authenticated account on success and the upstream error on failure, and it keeps working even on plans that no longer include integrations.
  • A run that failed. Open the capability’s history. Each failed run lists the repositories, teams, or documentation sections that failed and the error from the provider.
  • Nothing is running. Confirm the capability’s toggle is on and its schedule isn’t blank — a capability with no schedule only runs when you trigger it.
  • Transient upstream errors. Runs handle these themselves — repository scans wait out a provider’s rate limit before continuing, and team syncs retry rate-limited or failing requests a few times, honouring the provider’s Retry-After. What survives that is recorded in the run’s errors.
Section titled “Related”