How to connect Bitbucket to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Bitbucket from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Bitbucket tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Bitbucket call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

The causes the engines teach for this error are: the account lacks repository permissions, the credential lacks scopes, an IP allowlist blocks the caller, the workspace or repository slug is wrong, or a stale token needs re-auth. In a hosted connection the credential-scope cause does not exist, and the real checks are account-level. The connected account must have repository-level access for the specific repo, not just workspace access; some endpoints are workspace-admin-only; and a wrong workspace or repo slug in the request fails as a permission error rather than a not-found. Two hosted-specific checks come next: an IP allowlist on the account or workspace can block the hosted connection's calls entirely, which no amount of reconnecting fixes, and a placeholder id from documentation fails like a permission error, so ask the agent to run a browse or get tool first and use a real slug from those results.

Ask the agent to diagnose it:

Run bitbucket_browse_repository_path for the repo in question and show me the real workspace and repo slugs. Quote the exact 403 text, then retry with the real slugs. If the error names IP restrictions, tell me before reconnecting.

Bitbucket's documented base limit is 1,000 requests per hour, rolling, and a 429 is the response when an agent walks a large repository one call at a time: every file, then every commit, then every PR, each a separate request. The response is not to retry immediately, which lands in the same hour window, but to change the shape of the work: one path or one PR at a time, and have the agent tell you what it intends to enumerate before it starts. If a bulk audit is genuinely needed, running it in stages across turns is more reliable than one sweep, and a plain read of a repo's file tree is far cheaper than walking every file's contents.

Ask the agent to diagnose it:

Tell me how many Bitbucket calls you have made in the last hour and what you were enumerating. Quote any rate-limit text from the last response. Do not call Bitbucket again until I reply.

Two different failures. If Hermes shows no Bitbucket tools at all, the connection or pairing is incomplete: confirm the plugin was installed with --enable, that both hermes clawlink begin and hermes clawlink finish ran, that Bitbucket shows as connected in the dashboard, and start a fresh chat. If most tools work and a single name fails, that name is wrong rather than missing: the error lists the closest real tools, and the real catalog is one clawlink_list_tools --integration bitbucket away. There is also a first-call timing case unique to this setup: schemas load on demand, so the opening Bitbucket call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the advice for this symptom that assumes a local MCP server declared in an mcp.json with env vars, which is what the search results teach.

Ask the agent to diagnose it:

List the Bitbucket tools you actually have access to. If there are none, run clawlink_list_integrations and confirm the plugin pair, then tell me what you see. If there are, tell me which one reads a file from a repository and use that exact name.

Try reconnecting Bitbucket and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Bitbucket: link your Bitbucket account once in the browser and Hermes Agent can call the Bitbucket API through 105 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Bitbucket in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Bitbucket in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Bitbucket working from chat.

No, and the timing makes this worth stating plainly. Atlassian removed app passwords on 2026-07-28, so the app-password flows every older tutorial teaches now fail, and the replacement the docs point to is generating an Atlassian API Token. This page needs neither: the plugin pairs once through hermes clawlink begin and finish, Bitbucket authorizes on its own consent screen in the browser, and the connection is stored server-side. There is no credential on the Hermes machine to deprecate, rotate, or leak, and disconnecting from the dashboard revokes the agent's access immediately.

The 105 tools cover the repository surface: repositories and their contents, pull requests and their diffs, comments, and approvals, branches, issues, commits and their build statuses, and commit reports. The writes to be deliberate about are pull requests, branches, and approvals, because they appear in other people's review workflow. Reads come first, and the pull-request review surface is the part teams actually use: an agent that reads a PR diff and its comments is more useful than one that creates branches on demand.

The AI Overview answers this query with "generally safe with official integrations plus least-privilege", and its named risks are prompt injection, over-privileged tokens, unverified third-party MCP servers, and IP allowlists. The hosted connection removes the token half: there is no over-privileged token to create, because the grant is the account itself, and no third-party MCP server to vet, because the plugin is the integration. The behavioral half is yours: treat repo content as untrusted input, start with reads, require confirmation before writes like creating PRs or approving changes, and know that if your workspace restricts access by IP, the hosted connection's calls can be blocked entirely.

The underlying Bitbucket API is the same, so the capability difference is small; the setup and upkeep difference is not. The Composio route the AI Overview teaches starts with piping their install script into a shell, then hand-editing ~/.hermes/config.yaml with an MCP server block and a consumer key, infrastructure you then own. Here the plugin install and one pairing handshake are the entire client-side story, and Bitbucket sits alongside your other connected accounts with one place to revoke. Choose on how much you want to run, not on features.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.