Hermes Agent Integration with Bitbucket: The Complete Setup Guide

You have a Bitbucket repository with a growing backlog of pull requests, a CI pipeline that occasionally flakes, and a team that's stretched thin. You've heard about AI coding agents, but the last thing you need is another tool that adds more complexity to your workflow.

What if your agent could clone repos, review pull requests, trigger pipelines, and respond to Bitbucket webhooks -- all from your terminal, without switching contexts?

That's what happens when you connect Hermes Agent to Bitbucket. This guide walks through every step of the integration: prerequisites, authentication, configuration, environment variables, common workflows, and the gotchas that only show up after you've already banged your head against the wall for an hour.

What Is Hermes Agent?

Hermes Agent is an open-source AI agent framework by Nous Research. Think of it as a coding assistant that lives in your terminal, works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 20+ others), and can run on Windows, macOS, and Linux.

What makes Hermes different from other agents:

Self-improving through skills -- it learns from experience and saves reusable procedures
Persistent memory across sessions -- remembers your preferences and environment
Multi-platform gateway -- runs on Discord, Telegram, Slack, email, and more
Provider-agnostic -- swap models without changing anything else
Extensible -- plugins, MCP servers, custom tools, webhooks, and cron scheduling

Hermes uses tool calling to interact with your system -- running shell commands, reading and writing files, searching the web, and executing Python code. When you integrate it with Bitbucket, those tool calls reach your repositories, pull requests, and pipelines.

Why Connect Hermes to Bitbucket?

Before we get into the mechanics, let's talk about what this integration actually buys you:

Review pull requests without opening a browser. Hermes can fetch PR diffs, analyze changes, and leave inline comments.
Automate repetitive git workflows. Merge staging into main, cherry-pick hotfixes, clean up stale branches -- all from a natural language command.
Trigger pipelines on demand. Run Bitbucket Pipelines builds, check their status, and report results back in your chat platform of choice.
Respond to webhook events. When someone pushes to a repo or opens a PR, Hermes can pick up the context and act on it.
Context-aware code changes. Hermes reads your repository structure, understands the codebase, and makes changes that fit the existing patterns.

This isn't about replacing your team's workflow. It's about eliminating the context switches that fragment your focus.

Prerequisites

Before you start, make sure you have these in place:

Hermes Agent

Hermes installed (latest version). If you haven't installed it yet:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Or via pip:

pip install hermes-agent

Run hermes setup to configure your model provider and terminal backend
Run hermes doctor --fix to resolve any dependency issues

Bitbucket Account

A Bitbucket Cloud account (or Bitbucket Data Center/Server with API access)
A repository to work with -- create one if you're just testing
For Bitbucket Cloud: an App Password with the appropriate permissions (we'll cover which ones you need)

Git

Git installed and configured on your machine

git --version
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Optional but Recommended

SSH key configured for Bitbucket (avoids password prompts during git operations)
Python 3.9+ for running automation scripts alongside Hermes

Authentication: Getting Hermes Access to Bitbucket

You have three options for authenticating Hermes with Bitbucket. Choose the one that fits your workflow.

Option 1: Bitbucket App Password (Recommended for Cloud)

App passwords are the simplest and most secure way to give Hermes API access to Bitbucket Cloud.

Go to Bitbucket Settings > App Passwords (or visit https://bitbucket.org/account/settings/app-passwords/)
Click Create app password
Give it a label like "Hermes Agent Integration"
Select the permissions you need (be specific -- don't over-permission):

Minimum for read-only operations:
- Repositories: Read
- Pull Requests: Read
- Pipelines: Read
For full integration (write operations):
- Repositories: Read & Write
- Pull Requests: Read & Write
- Pipelines: Read & Write
- Webhooks: Read & Write
For commit status updates:
- Commit statuses: Read & Write
Click Create. Copy the generated password immediately -- you won't see it again.

Option 2: SSH Key Authentication

If you prefer SSH (for direct git operations without API calls):

Generate an SSH key if you don't have one:

ssh-keygen -t ed25519 -C "hermes-agent@your-email.com"

Add the public key to Bitbucket:
- Go to Bitbucket Settings > SSH Keys
- Click Add key and paste the contents of ~/.ssh/id_ed25519.pub
Test the connection:
```
ssh -T git@bitbucket.org
```

Option 3: OAuth (For Bitbucket Data Center / Server)

If you're self-hosting Bitbucket, create an OAuth consumer:

Go to Bitbucket Administration > OAuth > Add consumer
Set the callback URL (a placeholder like http://localhost:7990 works for CLI use)
Grant the appropriate permissions
Note the Client ID and Secret

Environment Variables

Store your Bitbucket credentials in Hermes's .env file so they're available in every session without being exposed in your command history.

# Open Hermes's .env file
hermes config env-path   # prints the path, typically ~/.hermes/.env

Add these variables:

# Bitbucket Cloud Credentials (App Password)
BITBUCKET_USERNAME=your-bitbucket-username
BITBUCKET_APP_PASSWORD=your-generated-app-password

# For SSH-based git operations (optional, usually auto-detected)
GIT_SSH_COMMAND=ssh -i ~/.ssh/id_ed25519

# Bitbucket Server/Data Center (if applicable)
BITBUCKET_BASE_URL=https://your-bitbucket-instance.com
BITBUCKET_CLIENT_ID=your-oauth-client-id
BITBUCKET_CLIENT_SECRET=your-oauth-client-secret

# Default workspace and project (optional, saves typing)
BITBUCKET_DEFAULT_WORKSPACE=your-workspace
BITBUCKET_DEFAULT_PROJECT=your-project

After setting these, run /reload in Hermes (or start a new session) so the environment is picked up.

Step-by-Step Integration

Step 1: Verify Hermes Can Reach Bitbucket

Start a Hermes session and run a quick connectivity check:

hermes

Then ask Hermes to verify the connection:

"Check if I can reach Bitbucket's API. Use my BITBUCKET_USERNAME and BITBUCKET_APP_PASSWORD from the environment. List my repositories."

Hermes will use curl or a Python script to hit the Bitbucket API and return your repos. If you see your repository list, you're authenticated.

Step 2: Clone a Repository

You can ask Hermes to clone a repo directly:

"Clone the repository from bitbucket.org/myworkspace/myproject into ~/projects/myproject. Use HTTPS with my Bitbucket app password for authentication."

Hermes will run:

git clone https://$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD@bitbucket.org/myworkspace/myproject.git ~/projects/myproject

For subsequent operations, Hermes can work inside the cloned repo to make changes, create branches, and push commits.

Step 3: Configure the Bitbucket Webhook (Event-Driven Automation)

This is where the integration gets powerful. Bitbucket webhooks let Hermes respond automatically to repository events.

On the Bitbucket side:

Go to your repository > Repository Settings > Webhooks
Click Add webhook
Set the title to "Hermes Agent"
Set the URL to your Hermes webhook endpoint. If Hermes is running locally, you'll need a tunnel service like ngrok or Cloudflare Tunnel:
```
ngrok http 8080
```
This gives you a URL like https://abc123.ngrok.io
Choose the events you want Hermes to respond to:
- Pull Request: Created -- auto-review new PRs
- Pull Request: Updated -- re-review after changes
- Push -- trigger analysis or deployment
- Pipeline: Completed -- react to build results

On the Hermes side:

Subscribe to the webhook in Hermes:

hermes webhook subscribe pr-reviewer \
  --route /webhooks/bitbucket-pr \
  --description "Auto-review Bitbucket PRs"

Hermes listens for incoming POST requests on this route and can process the payload to determine what action to take.

Step 4: Set Up a PR Review Workflow

This is the flagship use case. Let Hermes review pull requests automatically.

With the webhook configured, tell Hermes what you want it to do when a PR arrives:

"When a Bitbucket PR webhook arrives, I want you to fetch the diff, review it for code quality, security issues, and consistency with the codebase, then post a summary comment on the PR. Use the Bitbucket API to post comments."

You can save this as a Hermes skill so it persists across sessions:

"Save this PR review workflow as a skill called 'bitbucket-pr-reviewer' so it loads automatically on webhook events."

When a PR is created, Hermes:

Receives the webhook payload with the PR URL, source branch, and repository info
Clones or fetches the repository
Gets the diff via git diff or the Bitbucket API
Analyzes the changes
Posts a review comment via the Bitbucket API

Step 5: Automate Pipeline Triggers

Run pipelines on demand using natural language:

"Trigger the main pipeline on the staging branch and tell me when it finishes."

Hermes can call the Bitbucket Pipelines API:

curl -X POST \
  -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"target":{"ref_type":"branch","ref_name":"staging","type":"pipeline_ref_target"}}' \
  "https://api.bitbucket.org/2.0/repositories/$WORKSPACE/$REPO/pipelines/"

Then poll for completion and report the result.

Testing the Integration

Run these tests to verify everything works end-to-end:

Test 1: API Connectivity

# In Hermes session
curl -s -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/user" | jq .display_name

If you see your account name, the credentials work.

Test 2: Repository Access

# List branches in a repo
curl -s -u "$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD" \
  "https://api.bitbucket.org/2.0/repositories/$WORKSPACE/$REPO/refs/branches" | jq '.values[].name'

Test 3: Git Operations

# Clone and perform a basic git operation
git clone https://$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD@bitbucket.org/$WORKSPACE/$REPO.git /tmp/test-integration
cd /tmp/test-integration
git log --oneline -5

Test 4: Webhook Delivery

Create a test PR or push a commit and verify Hermes receives the webhook. Check the gateway logs:

grep "bitbucket" ~/.hermes/logs/gateway.log | tail -20

Test 5: PR Review

"Review the latest PR in myworkspace/myproject on Bitbucket. Summarize what it changes and flag any issues."

Common Issues (and What Actually Fixed Them)

"Authentication failed" on git clone

The fix: If your Bitbucket username has special characters (like @ or .), URL-encode them. Better yet, store credentials in git's credential helper:

git config --global credential.helper store
echo "https://$BITBUCKET_USERNAME:$BITBUCKET_APP_PASSWORD@bitbucket.org" > ~/.git-credentials

Webhook not reaching Hermes

The fix: If Hermes is running locally, Bitbucket can't reach your machine. Use a tunnel:

ngrok: ngrok http 8080 (free tier works for testing)
Cloudflare Tunnel: cloudflared tunnel --url http://localhost:8080

Then update the webhook URL in Bitbucket settings.

"403 Forbidden" from Bitbucket API

The fix: Your App Password doesn't have the required permissions. Go back to Bitbucket Settings > App Passwords and verify the permissions match what you're trying to do. If you're posting PR comments but only granted read permissions, that's your culprit.

Pipeline trigger succeeds but no output

The fix: Pipelines run asynchronously. The trigger endpoint returns a 202 Accepted immediately, but the pipeline might still be queued. Use the returned pipeline UUID to poll for completion:

curl -s -u "$USER:$PASS" \
  "https://api.bitbucket.org/2.0/repositories/$WS/$REPO/pipelines/$UUID" | jq '.state'

Git asks for password repeatedly

The fix: Switch to SSH authentication for git operations, or use a credential helper. HTTPS with App Passwords works for the first clone, but subsequent fetches can prompt for credentials if the remote URL format isn't consistent.

Best Practices

Use the principle of least privilege. Create a dedicated App Password with only the permissions your integration needs. A reviewer doesn't need admin access.

Store credentials in Hermes's .env, not your shell history. Hermes loads .env at startup and redacts secrets from tool output by default. This keeps your tokens out of logs and conversation history.

Save workflows as Hermes skills. When you get a Bitbucket workflow working -- like PR review or pipeline monitoring -- save it as a skill:

"Save this PR review workflow as a skill called 'bitbucket-pr-review' so I can reuse it later."

Skills persist across sessions and can be loaded with /skill bitbucket-pr-review.

Test webhooks with a simple echo first. Before wiring up complex automation, point your webhook at a request bin service like webhook.site to verify the payload structure. Then point it at Hermes.

Use SSH for git, App Passwords for API. SSH handles git authentication seamlessly with no credential prompts. App Passwords handle Bitbucket API calls for PRs, pipelines, and webhooks. They serve different purposes -- use both.

Keep your App Password rotation on a calendar. Rotate tokens every 90 days. When you rotate, update Hermes's .env and run /reload in your session.

Monitor gateway logs for webhook failures. Bitbucket will display delivery status for each webhook call. If Hermes isn't responding, check both Bitbucket's webhook log and ~/.hermes/logs/gateway.log:

tail -f ~/.hermes/logs/gateway.log | grep -i bitbucket

The Pivot: When Not to Automate

Let's be honest -- not every PR needs an AI review. If your team ships twenty small documentation fixes a day, auto-reviewing every one of them will generate noise, not value. And a complex architectural decision involving tradeoffs across three services is still something a human should weigh in on.

The sweet spot is mechanical consistency checks: formatting, missing error handling, security anti-patterns, API contract violations. Let Hermes catch what machines catch best, so your team can focus on what only humans can decide.

Next Steps

Clone a test repository, configure your App Password, and ask Hermes one thing: "What branches are on my Bitbucket repo?" The first time it comes back with a clean list, you'll feel the shift.

From there, try a PR review. Then a pipeline trigger. Then a webhook that runs a deployment check every time someone pushes to main. Each step removes a little more friction from your day.

And when you're ready to take this further -- building custom workflows, connecting Bitbucket events to downstream systems, or setting up a multi-agent pipeline that reviews code, runs tests, and deploys automatically -- that's where having the right implementation partner makes all the difference.

Talk to our team at Vistaran about setting up a production-grade Hermes Agent deployment with Bitbucket integration tailored to your workflow. We help teams move from "I wish my agent could do that" to "I can't imagine working without it."

Have you already integrated Hermes with Bitbucket? What workflow saved your team the most time? I'd love to hear what's working (and what surprised you) -- drop a comment below.