How to Authenticate and Submit Reviews to Bitbucket Cloud Pull Requests with tuicr

tuicr delegates all Bitbucket Cloud authentication and API operations to the external bkt CLI, requiring users to configure API tokens through bkt before submitting PR reviews via the TUI interface.

tuicr is a terminal-based code review tool that integrates with multiple forges including Bitbucket Cloud. To authenticate and submit reviews to Bitbucket Cloud PRs, tuicr relies entirely on the external bkt CLI tool rather than implementing its own OAuth flow or token storage mechanism.

Prerequisites and Authentication Setup

Before opening any pull requests, you must configure the bkt CLI with valid Bitbucket Cloud credentials. tuicr does not store tokens internally; instead, it invokes bkt for every authenticated operation.

Install the Bitbucket CLI:

brew install avivsinai/tap/bitbucket-cli

Authenticate with your API token:

bkt auth login https://bitbucket.org --kind cloud --web-token

This command opens Atlassian's token creation page in your browser. Create an API token with pull-request read and write scopes, paste it into the prompt, and bkt will store it in your OS keychain or credential store. Verify the configuration with:

bkt auth status

Opening a Pull Request in tuicr

Once authenticated, tuicr detects Bitbucket Cloud repositories by scanning Git remotes. In src/forge/mod.rs (lines 23-30), the forge detection logic creates a BitbucketBktBackend when it encounters remotes hosted on bitbucket.org, altssh.bitbucket.org, or api.bitbucket.org.

Open a specific PR using:

tuicr pr 830

The BitbucketBktBackend::get_pull_request_diff method in src/forge/bitbucket/bkt.rs (lines 20-26) fetches the diff by shelling out to bkt pr diff.

Submitting Reviews via the TUI

Inside the tuicr interface, press : to enter command mode, type submit, and press Enter. The TUI presents a picker offering Comment or Approve events for Bitbucket Cloud.

Posting Comments and Approvals

When you confirm a submission, tuicr builds a CreateReviewRequest and delegates to BitbucketBktBackend::create_review in src/forge/bitbucket/bkt.rs (lines 31-39). This method executes three distinct operations:

• Posts an optional review-level comment via post_comment (lines 101-108)
• Posts inline comments with anchors built by inline_anchor (lines 33-50)
• Approves the PR via bkt pr approve if you selected Approve (lines 75-85)

All bkt commands execute through the BktCommandRunner abstraction, which calls run_command_output("bkt", …).

Key Implementation Details

Repository Resolution and SHA Handling

The parse_bitbucket_remote_url function (lines 37-47 and 59-70 in src/forge/bitbucket/bkt.rs) validates that remotes point to bitbucket.org hosts and extracts the workspace and repository name. This guarantees that self-hosted Bitbucket Data Center instances are rejected during backend initialization.

Bitbucket's API returns 12-character commit hashes in PR payloads. tuicr expands these to full 40-character SHA1s via promote_sha (lines 27-44) to ensure stable session keys for review threads.

Error Handling and Security

Authentication errors map to user-friendly messages through map_bkt_error (lines 93-111). If bkt auth status indicates an expired or missing token, tuicr surfaces a TuicrError::Forge variant with specific guidance rather than exposing raw CLI errors.

Complete Workflow Example

Full setup and review submission:

# Install dependencies

brew install avivsinai/tap/bitbucket-cli

# Authenticate (one-time setup)

bkt auth login https://bitbucket.org --kind cloud --web-token
bkt auth status

# Navigate to repository and open PR

cd my-bitbucket-repo
tuicr pr 830

# Inside tuicr:

# 1. Review the diff

# 2. Press : to open command palette

# 3. Type 'submit' and select Comment or Approve

# 4. Confirm with 'y'

For automated testing without posting comments:

TUICR_BB_WORKSPACE=myteam \
TUICR_BB_REPO=my-service \
TUICR_BB_PR=830 \
cargo test bitbucket_live -- --ignored --nocapture

This executes the read-only test suite defined in the source that validates authentication and diff fetching without mutating the pull request.

Summary

• tuicr requires the external bkt CLI for all Bitbucket Cloud operations; it never stores credentials internally
• Authentication uses bkt auth login with API tokens stored in the OS keychain
• The BitbucketBktBackend in src/forge/bitbucket/bkt.rs handles PR diff retrieval, comment posting, and approvals
• Bitbucket Cloud remotes are detected via parse_bitbucket_remote_url, which explicitly ignores Data Center instances
• Submit reviews by pressing :submit in the TUI, choosing between Comment or Approve, and confirming

Frequently Asked Questions

Does tuicr support Bitbucket Data Center or Server?

No. The parse_bitbucket_remote_url function explicitly validates hosts against bitbucket.org, altssh.bitbucket.org, and api.bitbucket.org. Self-hosted Data Center instances are rejected during remote URL parsing in src/forge/bitbucket/bkt.rs.

Where are my Bitbucket credentials stored?

tuicr does not store credentials. The bkt CLI stores your API token in the native OS credential store (macOS Keychain or Linux credential store). tuicr only checks authentication status by running bkt auth status before executing commands.

How do I submit an approval instead of just comments?

In the tuicr TUI, press : to open the command palette, type submit, and select Approve from the picker. The create_review method will post your inline comments and then execute bkt pr approve to add the approval state to the pull request.

What happens if my API token expires?

The map_bkt_error function in src/forge/bitbucket/bkt.rs translates bkt authentication failures into TuicrError::Forge messages. You will see a prompt indicating the authentication error, and you must run bkt auth login again to refresh your token before resuming reviews.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}