Connecting Integrations

Clears AI integrates with your version control system, Jira, and Slack to fit into your existing workflow. A VCS provider (GitHub, GitLab, or Bitbucket) is required; Jira and Slack are optional but recommended for the full experience.

You can connect integrations during onboarding or at any time from Settings → Integrations.

GitHub

GitHub is connected via a GitHub App installation. Clears AI uses it to read your codebase, create branches, commit code, and open pull requests.

Installing the GitHub App

1. Navigate to Settings → Integrations → GitHub
2. Click Install GitHub App
3. A popup opens on GitHub — select the organization or user account
4. Choose repository access:
   • All repositories — grants access to every repo in the org
   • Select repositories — pick specific repos
5. Click Install & Authorize
6. The popup closes and your connection status updates

Configuring Execution Repositories

After installing the app, you need to select which repositories the AI agent can work in:

1. In the GitHub integration page, find the Execution Repositories section
2. Select the repositories where you want the AI to create branches and PRs
3. Click Save

These are the repos that appear as options when you create a story on the Board. You can change this list at any time.

Configuring Base Branches

For each execution repository, you can configure which base branch the AI uses when creating feature branches. By default, Clears AI looks for branches in this order: develop → dev → main → master. You can override this per repository in the GitHub settings or when creating a story.

For more details, see the GitHub Integration admin page.

GitLab

GitLab is connected via OAuth. Clears AI uses it to read your codebase, create branches, commit code, and open merge requests in your GitLab projects.

Connecting via OAuth

1. Navigate to Settings → Integrations → GitLab
2. Click Connect with OAuth
3. A popup opens to GitLab's OAuth authorization screen
4. Grant Clears AI access to your GitLab.com group
5. The popup closes and your connection status updates, displaying your group name

Configuring Execution Repositories

After connecting, you need to add projects for AI execution:

1. In the GitLab integration page, browse the Projects table
2. Use Search to filter projects by name, and pagination controls to navigate large lists
3. Click + Add next to a project to register it for AI execution — this also registers a webhook on the project
4. Click Unuse to remove a project from the execution list

Only projects added for execution appear as options when creating stories on the Board.

Excluded Paths

If your group contains projects you don't need (archived repos, forks, internal tooling), you can hide them:

1. Open the Excluded Paths section
2. Type a path prefix (e.g., my_group/archived) and press Enter
3. Projects matching any excluded prefix are hidden from the list
4. Click Save to apply

For more details, see the GitLab Integration admin page.

Bitbucket

Bitbucket is connected via OAuth. Clears AI uses it to read your codebase, create branches, commit code, and open pull requests in your Bitbucket Cloud repositories.

Connecting via OAuth

1. Navigate to Settings → Integrations → Bitbucket
2. Click Connect with OAuth
3. A popup opens to Bitbucket's OAuth authorization screen
4. Grant Clears AI access to your Bitbucket Cloud account
5. The popup closes and your connection status updates

Configuring Your Workspace

After connecting, you need to set your workspace before repositories are listed:

1. In the Repositories section, find the Workspace slug field
2. Enter your workspace slug — the first path segment of your repository URLs (e.g., for bitbucket.org/clearsai/my-repo, the workspace slug is clearsai)
3. Click Save

Once the workspace is saved, the repository list populates automatically.

Configuring Execution Repositories

After configuring your workspace, select which repositories the AI agent can work in:

1. Open the Execution Repositories section
2. Use the multi-select dropdown to choose repositories from your workspace
3. Click Save to apply changes, or Discard to revert unsaved selections

Only selected repositories appear as options when creating stories on the Board.

For more details, see the Bitbucket Integration admin page.

Jira

Jira integration syncs stories between your Jira backlog and the Clears AI Board.

Connecting via OAuth

1. Navigate to Settings → Integrations → Jira
2. Click Connect Jira
3. Sign in to your Atlassian account in the popup
4. Authorize Clears AI to access your workspace
5. Your Jira domain appears once connected (e.g., your-team.atlassian.net)

Setting Up the Webhook

The webhook allows Jira to notify Clears AI when issues change:

1. In the Jira integration page, copy the Webhook URL
2. In Jira, go to Settings → System → WebHooks
3. Create a new webhook:
   • Name: Clears
   • URL: paste the URL from step 1
   • Events: check Issue Created, Issue Updated, Issue Deleted
4. Back in Clears AI, generate and save the webhook secret

Adding Required Statuses

Clears AI uses custom Jira statuses to track the execution pipeline. Add these statuses to your Jira projects:

Status	Category	Description
Enriched	In Progress	Story analyzed, spec generated
Product Approved	In Progress	Spec approved, ready for decomposition
Ready For Dev	In Progress	Subtasks created, implementation starting
Validation	In Progress	PRs created, awaiting review

You can use the Jira Project Statuses audit tool in Settings (admin only) to check which projects have these statuses configured and auto-create any that are missing.

Slack

Slack enables notifications when stories need attention and supports interactive Q&A during story analysis.

Connecting Your Workspace

1. Navigate to Settings → Integrations → Slack
2. Click Install Slack App
3. Select your Slack workspace in the popup
4. Authorize Clears AI

Once connected, Clears AI can:

• Send direct messages when stories need your input (e.g., Q&A questions)
• Notify you when PRs are ready for review
• Alert you when execution completes or fails

Without Slack

If you skip Slack integration, all interactions happen directly on the Clears AI Board. Q&A questions appear in the story detail panel, and you can monitor status through the kanban view.

Verifying Your Setup

After connecting your integrations, verify everything is working:

1. VCS provider: Check that your repositories (or projects, for GitLab) appear in the execution repos list
2. Jira (if connected): Verify the webhook secret is saved and the domain is displayed
3. Slack (if connected): Confirm the workspace name appears on the integration page

You're now ready to create your first AI story.