Integrations

cliq connects to external services through the integrations block in settings.json. Each integration is configured once in your global settings (~/.cliqrc/settings.json) and is available to every project. Project-level overrides in .cliq/settings.json are deep-merged on top.

{
  "integrations": {
    "github": { ... },
    "bitbucket": { ... },
    "jira": { ... },
    "slack": { ... },
    "google": { ... },
    "microsoft": { ... }
  }
}

Six integrations are supported. Each section below covers what it’s used for, how to set it up, the full settings reference, and how to verify it.

---

GitHub

GitHub integration powers the git lifecycle — branch creation, commit, push, and pull request automation. It’s used by the git-setup and git-finalize agents, and by the pr-exists and create-pr tools.

1. Create a Personal Access Token

1. Go to https://github.com/settings/tokens
2. Click Generate new token → Fine-grained token (recommended)
3. Give it a name (e.g., cliq)
4. Set Expiration to your preference
5. Set Repository access to the repos you’ll use cliq with (or “All repositories”)
6. Under Permissions → Repository permissions, grant:

Permission	Level	Why cliq needs it
Contents	Read and write	Push commits and branches
Pull requests	Read and write	Create PRs, add reviewers, verify PR exists

7. Leave all other permissions at “No access”
8. Click Generate token and copy it immediately

Classic tokens also work — select the repo scope. Fine-grained tokens are recommended for least-privilege access.

2. Configure

{
  "integrations": {
    "github": {
      "token": "github_pat_YOUR_TOKEN_HERE",
      "base_branch": "main",
      "remote": "origin",
      "branch_prefix": "cliq/",
      "finalize_to": "pr",
      "pr_draft": false,
      "pr_reviewers": [],
      "pr_labels": ["cliq-generated"]
    }
  }
}

Settings reference

Field	Type	Default	Description
token	string	""	GitHub Personal Access Token. Required for PR operations.
base_branch	string	"main"	Branch to create feature branches from and merge back to
remote	string	"origin"	Git remote name
branch_prefix	string	"cliq/"	Prefix for feature branches (e.g., cliq/PROJ-123)
finalize_to	string	"pr"	Automation boundary — how far git-finalize goes
pr_draft	boolean	false	Create PRs as drafts
pr_reviewers	string[]	[]	GitHub usernames to request review from
pr_labels	string[]	["cliq-generated"]	Labels to apply to created PRs

Only token is required in global settings. The rest can be overridden per-project.

finalize_to options

Controls the automation boundary — the point at which cliq hands off to a human:

Value	What happens
commit	Stage and commit only. Human pushes and creates PR.
push	Commit and push. Human creates PR.
pr	Commit, push, and create PR via GitHub API. Human reviews and merges. (default)

If finalize_to is pr but no token is configured, the agent falls back to push and logs a warning.

3. Verify

cliq doctor test github

If you’re in a git repo, this checks token validity and repo access. Otherwise it verifies authentication only.

Used by

• Git Pipeline (git-setup, git-finalize, git-resolver agents)
• CLI Tools (pr-exists, create-pr)

---

Bitbucket Cloud

Bitbucket integration provides the same git lifecycle as GitHub — PR creation, verification, and branch management — for Bitbucket Cloud repositories. The provider is auto-detected from your git remote URL.

1. Find your workspace slug

Your workspace slug appears in your Bitbucket repo URLs:

https://bitbucket.org/<workspace>/<repo>

For example, if your repo URL is https://bitbucket.org/m1ai/myproject, your workspace slug is m1ai.

2. Find your Atlassian account email

This is the email you use to log in to Bitbucket / Atlassian:

1. Go to https://bitbucket.org/account/settings/
2. Under Email aliases, note your primary email address

3. Create a Bitbucket API token

1. Go to https://bitbucket.org/account/settings/app-passwords/
2. Click Create API token
3. Give it a label (e.g., cliq)
4. Check exactly these four scope boxes:

Category	Level	Why cliq needs it
Repositories	Read	Read source code, browse repo contents
Repositories	Write	Push commits and branches
Pull requests	Read	pr-exists verification check
Pull requests	Write	Create and merge pull requests

Important: In Bitbucket’s permission model, Write does NOT imply Read. You must check both Read and Write for each category.

5. Workspace scoping (recommended) — if prompted, scope the token to your workspace. Tokens cannot be scoped to a single repository — workspace is the most granular option.
6. Leave all other categories unchecked
7. Click Create and copy the token immediately — you cannot view it again

4. Configure

{
  "integrations": {
    "bitbucket": {
      "workspace": "m1ai",
      "email": "[email protected]",
      "api_token": "your-api-token-from-step-3"
    }
  }
}

Settings reference

Field	Type	Default	Description
workspace	string	""	Bitbucket workspace slug (from your repo URLs)
email	string	""	Atlassian account email (used for API authentication)
api_token	string	""	Bitbucket API token with Repos R/W + PRs R/W scopes
base_url	string	"https://api.bitbucket.org/2.0"	API base URL (override for self-hosted)

5. Verify

cliq doctor test bitbucket

GitHub vs Bitbucket

Feature	GitHub	Bitbucket Cloud
Auth	Personal Access Token	API token (email + token)
Token scopes	Per-permission fine-grained	4 checkboxes (Repos R/W, PRs R/W)
Scope granularity	Per-repository	Per-workspace
Draft PRs	Supported (pr_draft: true)	Not supported (ignored)
Reviewers	By GitHub username	By Bitbucket username
Labels	Supported (pr_labels)	Not supported (ignored)
API	api.github.com	api.bitbucket.org/2.0

Git provider auto-detection

The git hosting provider is auto-detected from the origin remote URL. No manual configuration is needed.

Remote URL contains	Provider used
bitbucket.org	Bitbucket Cloud
Anything else	GitHub

If no remote is configured, cliq falls back to whichever integration has credentials set. All git operations (branch, commit, push) are provider-agnostic — only PR creation and PR verification use the provider API.

Used by

• Git Pipeline (git-setup, git-finalize, git-resolver agents)
• CLI Tools (pr-exists, create-pr)

---

Jira

Jira integration serves two purposes: fetching ticket requirements (cliq req -s jira:KEY) and posting pipeline notifications (comments and ticket transitions) as work progresses.

1. Find your Jira instance URL

• Jira Cloud: https://your-org.atlassian.net
• Jira Server / Data Center: https://jira.your-company.com

2. Create a Jira API token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label (e.g., cliq)
4. Click Create and copy the token

Jira API tokens have no scopes or permission settings. The token inherits the full permissions of your Atlassian account. As long as your account has standard project member access, the token will work.

3. Find your Atlassian account email

Confirm at https://id.atlassian.com/manage-profile/email — use the primary email address.

4. Configure

{
  "integrations": {
    "jira": {
      "base_url": "https://your-org.atlassian.net",
      "email": "[email protected]",
      "api_token": "your-api-token-from-step-2"
    }
  }
}

Settings reference

Field	Type	Default	Description
base_url	string	""	Your Jira instance URL (no trailing slash)
email	string	""	Atlassian account email
api_token	string	""	Jira API token (generate here)

5. Verify

cliq doctor test jira                     # verifies authentication
cliq doctor test jira --ticket PROJ-123   # also verifies project access

How cliq uses Jira

Feature	Description
Fetch requirements	cliq req -s jira:PROJ-123 reads the ticket summary, description, and status
Post comments	On pipeline completion, escalation, or cancellation, a comment is added to the originating ticket
Transition tickets	On escalation, the ticket is moved to a configurable status (default: “Blocked”)

Jira notifications only fire when the req source is a Jira ticket (-s jira:KEY). See Notifications for event configuration and message examples.

Used by

• cliq req -s jira:KEY (requirement fetching)
• Notifications (Jira comment channel)

---

Slack

Slack integration posts pipeline notifications via an Incoming Webhook — start, complete, escalate, cancel, pull, and push events.

1. Create a Slack app

1. Go to https://api.slack.com/apps
2. Click Create New App → From scratch
3. Give it a name (e.g., cliq notifications) and pick your Slack workspace

2. Enable Incoming Webhooks

1. In the left sidebar, click Incoming Webhooks
2. Toggle it On
3. Click Add New Webhook to Workspace
4. Pick the channel you want notifications posted to (e.g., #engineering)
5. Click Allow
6. Copy the webhook URL — it looks like:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Configure

{
  "integrations": {
    "slack": {
      "webhook_url": "https://hooks.slack.com/services/T.../B.../..."
    }
  }
}

Settings reference

Field	Type	Default	Description
webhook_url	string	""	Slack Incoming Webhook URL

There is only one field — the webhook URL. No tokens or scopes to manage.

4. Verify

cliq doctor test slack

This sends a test message to the configured webhook. You should see it appear in your Slack channel.

Used by

• Notifications (Slack webhook channel)

---

Google (Drive, Docs, Sheets)

Google integration powers pull and push operations for Google Drive folders, Google Docs, and Google Sheets. Two authentication modes are supported.

Option A: Service account (default)

Best for Google Workspace organizations where a service account can access shared resources.

Setup:

1. Go to Google Cloud Console → Service Accounts
2. Create a service account and download the JSON key file
3. Enable the Google Drive API and Google Docs API for your project
4. Share target Drive folders and documents with the service account’s email address

{
  "integrations": {
    "google": {
      "credentials_file": "~/.cliqrc/google-service-account.json",
      "auth_mode": "service_account"
    }
  }
}

Service accounts have their own storage quota. For personal Google accounts, use OAuth instead.

Option B: OAuth2 (personal accounts)

Best for personal Google / Google One accounts where you want to push and pull as yourself.

Setup:

1. Go to Google Cloud Console → Credentials
2. Create an OAuth 2.0 Client ID (application type: Desktop app)
3. Download the JSON file and save it (e.g., ~/.cliqrc/google-oauth-client.json)
4. Enable the Google Drive API and Google Docs API for your project
5. Run cliq auth google — this opens a browser for one-time consent

{
  "integrations": {
    "google": {
      "oauth_client_file": "~/.cliqrc/google-oauth-client.json",
      "auth_mode": "oauth"
    }
  }
}

After consent, cliq stores a refresh token at ~/.cliqrc/google_token.json. All subsequent runs refresh the token automatically — fully headless, no browser needed.

Managing the token:

cliq auth google              # run the authorization flow
cliq auth google --status     # check if a token is stored and valid
cliq auth google --revoke     # revoke the token and clear local storage

Settings reference

Field	Type	Default	Description
auth_mode	"service_account" | "oauth"	"service_account"	Authentication method
credentials_file	string	""	Path to a Google service account JSON key file (service_account mode)
oauth_client_file	string	""	Path to an OAuth2 client secrets JSON file (oauth mode)

Verify

cliq doctor test google

Checks credentials (service account key or OAuth token) and verifies a successful token exchange with the Google API.

Used by

• Pull & Push — pull from Google Docs, Sheets, and Drive folders; push to Google Drive and Docs

---

Microsoft (SharePoint, OneDrive)

Microsoft integration powers pull and push operations for SharePoint document libraries and OneDrive. Authentication uses Azure AD client credentials.

Setup

1. Go to Azure Portal → App registrations
2. Register a new application
3. Under Certificates & secrets, create a client secret
4. Under API permissions, add these Application permissions:
   • Sites.ReadWrite.All (SharePoint)
   • Files.ReadWrite.All (OneDrive)
5. Grant admin consent for your organization

Configure

{
  "integrations": {
    "microsoft": {
      "tenant_id": "your-azure-tenant-id",
      "client_id": "your-app-client-id",
      "client_secret": "your-app-client-secret"
    }
  }
}

Settings reference

Field	Type	Default	Description
tenant_id	string	""	Azure AD tenant ID
client_id	string	""	Azure AD application (client) ID
client_secret	string	""	Azure AD client secret

Verify

cliq doctor test microsoft

Checks Azure AD credentials and verifies a successful token exchange.

Used by

• Pull & Push — pull from and push to SharePoint and OneDrive

---

Verify All Integrations

Test every configured integration at once:

cliq doctor test all

Unconfigured integrations are skipped (not treated as failures). Only integrations with credentials are tested.

You can also inspect your resolved settings with:

cliq status -v

This shows all integration settings with sensitive values masked.

---

Best Practices

• Put credentials in global settings (~/.cliqrc/settings.json) — tokens, API keys, email addresses, credential file paths
• Put project overrides in project settings (.cliq/settings.json) — base_branch, finalize_to, pr_labels, pr_reviewers
• Never commit credentials — add settings.json to .gitignore (cliq does this automatically during cliq assemble)
• Run cliq doctor test all after initial setup to catch misconfigurations before your first pipeline run
• Use fine-grained tokens for GitHub (per-repo, minimal permissions) and workspace-scoped tokens for Bitbucket

---

Troubleshooting

Error	Fix
”No GitHub token configured”	Set token in integrations.github. See GitHub above.
”No Bitbucket credentials configured”	Set email and api_token in integrations.bitbucket. See Bitbucket Cloud above.
”No Bitbucket workspace configured”	Set workspace in integrations.bitbucket — the slug from your repo URL (e.g., m1ai from bitbucket.org/m1ai/repo).
”Google integration not configured”	Set integrations.google.credentials_file (service account) or auth_mode: "oauth" + cliq auth google. See Google above.
”Microsoft integration not configured”	Set tenant_id, client_id, and client_secret in integrations.microsoft. See Microsoft above.
HTTP 401/403 on pull	Authentication failed. Check credentials and run cliq doctor test <provider>.
Slack webhook returns HTTP 403	The webhook URL is invalid or the Slack app was deleted. Regenerate it.
Jira returns HTTP 401	Verify base_url, email, and api_token. Run cliq doctor test jira.
”Transition ‘Blocked’ not available”	The status doesn’t exist on your Jira board. Check available transitions in the log message.