Integrations
Integrations overview
What integrations are, which kinds exist, who can add them and how each one connects.
An integration connects a workspace to an outside tool. CirCI reports builds to your git host, posts review notices to chat, files issues in your tracker and links screenshots to designs. Integrations belong to the workspace, and each project then chooses what it maps to: a repository, a channel, a tracker project or a design file.
The kinds
Section titled “The kinds”| Kind | Group in the dashboard | What it does | How it authenticates |
|---|---|---|---|
| GitHub | Git hosts | A CirCI / <build name> check with Approve and Reject buttons and one summary comment on the pull request, plus the /circi approve, /circi reject and /circi rerun commands |
The instance's GitHub App, installed on your account or organization. The connection stores only the installation ID |
| GitLab | Git hosts | A commit status and one summary note on the merge request, plus the same /circi commands |
An access token with the api scope |
| Bitbucket | Git hosts | A commit status and one summary comment on the pull request, plus the same /circi commands (no account can be linked for them yet) |
A workspace or repository access token, or an app password with its username |
| Slack | Chat | Review requested, overdue, rejected and approved notices in one channel per project | Installing the CirCI Slack app (OAuth) |
| Linear | Issue trackers | A Create issue button on the build, then the issue key | A personal API key |
| Jira | Issue trackers | A Create issue button on the build, then the issue key | Site address, account email and API token (Jira Cloud) |
| Figma | Design tools | A Figma frame chip on screenshots linked to a frame | A personal access token |
Azure DevOps, Microsoft Teams and Penpot appear in the Add integration dialog as Planned. Nothing is built for them.
Integrations are separate from outgoing webhooks, which are a project setting that sends signed JSON to your own services, and from sign-in providers, which let people sign in (an instance admin adds them in Instance settings).
Where you add them
Section titled “Where you add them”Open Workspace settings, then Integrations. The page lists the integrations you have added, grouped by kind, each with its logo. Add integration opens a dialog that lists every kind, searchable and filterable by group. A tile can say:
- Planned: the kind isn't built.
- Not set up on this server: the kind needs an app of its own on this instance (the GitHub App, the Slack app) and none is configured yet.
Adding an integration connects it. Its own page then maps projects to targets: which repository, channel, tracker project or Figma file each project uses. Some kinds also keep project-wide links there (Figma's frame links). A project can map to one git host and to one connection per tracker kind, and mapping it to another moves it.
If a provider rejects the stored credentials (a revoked token, an uninstalled app), the integration is flagged as needing attention. The page shows a banner with the reason, and no notices go out for it until you reconnect. Connecting the same account again replaces its credentials and clears the flag for git hosts, and Slack's Reinstall button does the same for Slack.
An external account connects to one workspace of the instance. A second workspace that tries the same GitHub installation, GitLab user, Bitbucket workspace or Figma account is refused with "That <kind> account is already connected to another workspace".
Who can add them
Section titled “Who can add them”Owners and admins of the workspace connect, map and remove integrations. Other members can look at the integrations and their mappings. Credentials are stored encrypted and never sent back to the dashboard. See Members and roles.
A GitHub link can also be made from a project's own settings page and by circi admin github link; see GitHub.
Events
Section titled “Events”The events a workspace's integrations can hear about are review.requested, review.overdue, build.rejected, build.approved and build.completed. Slack is the only chat integration and lets you choose among the first four per project. Git hosts get their status and comment from the build itself, not from these events. See Review requests and rules for when review requests are sent.