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, your Vendorian organization. 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

Integrations are organization-scoped and admin-only. Select the Organization settings button in the top right, 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. Which providers you can connect also depends on your plan: Pro and Enterprise include every provider below. A provider your plan doesn’t include is shown as a locked card naming the plans that do. If a plan change removes integrations, or one provider, the affected connections stay visible and can still be tested or deleted, but their capabilities stop running and can’t be reconfigured until the provider is available again. See Plans and limits.

What each provider can do

Provider	Repository scanning	Team sync	Documentation sync	Entity sync
GitHub	yes	yes	yes	—
GitLab	yes	yes	yes	—
Bitbucket	yes	—	yes	—
Atlassian	—	yes	—	—
Microsoft	—	yes	—	—
Vendorian	—	—	—	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.
• Vendorian vendor sync — mirror the vendors you manage in Vendorian as catalog entities.

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. Componecat tests the connection and saves it either way, then says whether the test passed. A connection whose test failed is saved unverified, so you can fix the credential on its page. No capability runs until you enable one.
4. On the integration’s page, choose Test connection to verify the credential again at any time. 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	Catalog Intake concurrency (optional, Catalog Intake)
GitLab	Personal access token, or a project access token	https://gitlab.com, or your self-managed instance	Catalog Intake concurrency (optional, Catalog Intake)
Bitbucket	Access token	https://bitbucket.org	Catalog Intake concurrency (optional, Catalog Intake)
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
Vendorian	Service-account OAuth client — client ID, client secret	Your Vendorian address	—

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

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.

GitLab tokens for opening merge requests

A catalog intake opens merge requests with a write token, which takes more than reading a repository. Whichever token you use, it needs the api scope (write_repository isn’t enough) and at least the Developer role on each project it writes to. The project also needs merge requests enabled in its settings, or the write check reports that they’re disabled. The token kind decides how far it reaches:

Token	Reaches
Personal access token	Every project its user has that role on
Group access token	The projects in its group
Project access token	Only its own project

A project access token can’t write across your organization’s repositories, so use one only when a single project is all you need. Against any other project, the write check reports that limit and suggests a personal or group access token.

Following a merge request after it’s open only takes reading, so a token with read_api on the integration is enough. That token has the same reach: a project access token can’t follow merge requests in other projects.

Bitbucket tokens for opening pull requests

On Bitbucket, a catalog intake opens pull requests. Its write token must be a Bitbucket access token with the Repositories: Write and Pull requests: Write scopes. Atlassian API tokens and app passwords don’t work, because integrations send the credential as a Bearer token. The kind of access token decides how far it reaches:

Token	Reaches
Repository access token	Only its own repository
Project access token	The repositories in its project
Workspace access token	The repositories in its workspace

Against a repository the token doesn’t reach, the write check reports that it can’t access or write to that repository, so use a project or workspace access token when an intake covers more than one repository.

Following a pull request after it’s open only takes reading, so the token on the integration needs the Pull requests: Read scope as well as read access to repositories. It has the same reach.

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. Most capabilities default to 0 */6 * * *, every six hours; entity sync defaults to hourly. Clear thinking about frequency pays off: every capability calls 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

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. Rotate it from the Webhook card on the integration’s page; each new secret is shown once. See Repository scanning. After that nobody can read it back, admins included: the integration’s settings never show it, and the audit log records a rotation without the value. If you lose the secret, or think someone may have seen it, rotate it and update your Git provider’s webhook.

GitLab connections can use a signing token instead, which GitLab generates and you paste into the same card. It’s stored encrypted and is never shown back either.

Catalog intake write credentials

A catalog intake can open a merge request adding a componecat.yaml to each repository it covers, which takes write access. The token on your integration only needs to read, and it should stay that way, so an organization admin gives the intake a write token of its own instead. A token works on only one provider, so an intake that covers several integrations takes one token for each. Each belongs to that one intake and does not outlast it.

Set one under Merge requests on the intake’s page, or with the setCatalogIntakeWriteCredential mutation, naming the integration it’s for, which must be one the intake covers. With the mutation, pass the token as a GraphQL variable so it stays out of the query text. It must be one of these:

• A personal access token on GitHub (classic or fine-grained) or GitLab.
• A project or group access token on GitLab.
• A repository, project or workspace access token on Bitbucket, sent with the personal access token kind whichever of these it is.

GitHub App credentials aren’t accepted, because installation tokens expire within an hour and an intake can run for much longer. The mutation rejects those, any other token type, and a token that belongs to a different provider than the integration you named, with an explanation.

A token is encrypted before it’s stored, like an integration’s credential. After that nobody can read it back, admins included: writeCredentials says, for each integration the intake covers, whether it has one, and the audit log records each change without the value. A token is only ever used on the integration it was set for.

A token is deleted when:

• the intake is completed, canceled or undone, or an admin chooses Finish, which deletes all of the intake’s tokens;
• an admin deletes it with deleteCatalogIntakeWriteCredential, except while the intake is undoing, when its tokens stay until its merge requests are closed or kept open;
• an admin takes its integration out of a draft intake, or deletes the integration.

Merge requests that are already open stay open, except that undoing an intake first closes what its tokens can, and waits for you about any it can’t, before it deletes them. Componecat keeps following their state with the integration’s read credential, but it can no longer update them, and says so on the intake’s page.

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, documentation already pulled from Git, and entities created by entity sync — along with the kind and fields it set up — all remain in the catalog. They simply stop being updated, and entities that were read-only while synced become editable.

Any write token a catalog intake holds for the integration is deleted with it.

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, documentation sections, or records 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, honoring the provider’s Retry-After. What survives that is recorded in the run’s errors.

Related

• Catalog as code — the descriptor file that repository scanning ingests.
• Documentation and activity — where synced documentation lands.
• APIs — the programmatic surfaces for automation.