feat(bin): add Bitbucket Cloud as a third PR provider by cloud-practitioner · Pull Request #4 · cloud-practitioner/firstmate

cloud-practitioner · 2026-09-22T04:16:52Z

Intent

Bring the Bitbucket Cloud PR support into the upstream firstmate repository (kunchenguid/firstmate) as a pull request. The change adds Bitbucket Cloud as a third PR provider alongside GitHub and GitLab: URL parsing for Bitbucket PR links, curl+jq reads of the Bitbucket REST v2.0 PR record, poll and merge support, a green-status merge policy, and async 202 confirm-merged handling that mirrors the existing GitLab provider. It also passes the Bitbucket bearer token via a curl config file rather than argv (so it never appears in the process list), and registers a new docs/bitbucket-backend.md describing the config-file token delivery. This same change already merged on the cloud-practitioner/firstmate fork as PR #1 (#1, head commit d967563); it now needs to reach upstream.

What Changed

Added Bitbucket Cloud as a first-class PR provider alongside GitHub and GitLab, with URL parsing and validation for the https://bitbucket.org/<workspace>/<repo>/pull-requests/<n> format
Implemented Bitbucket REST API v2.0 calls via curl+jq (no CLI dependency) to read PR state, commit statuses, and perform merge operations with green-status verification and async 202 task-status handling
Implemented secure bearer-token delivery via encrypted curl config files (instead of argv) so credentials never appear in process listings; token resolution mirrors existing providers with FM_BITBUCKET_TOKEN environment fallback to .env
Added Bitbucket-specific merge strategies (--squash, --merge, --method, with --rebase and --allow-red explicitly refused), head-SHA race-condition detection via pre-merge re-read, and one-shot confirm-merged polling
Added comprehensive docs/bitbucket-backend.md documenting identity, authentication, state reading, merge behavior, and task concurrency
Added test suite for URL parsing, API calls, merge logic, and edge cases (tests/fm-pr-bitbucket.test.sh); updated security tests

Risk Assessment

✅ Low: The change is a well-bounded feature addition that cleanly integrates a third PR provider by following established patterns from GitHub and GitLab, with comprehensive tests, documentation, and security consideration for token handling.

Testing

Validated Bitbucket Cloud PR support through 16 comprehensive unit tests covering URL parsing, token resolution, PR state reading, pre-merge conditions, and merge execution (both synchronous and asynchronous). All tests passed. Verified implementation details: bearer token passed via chmod 600 curl config file (never on argv), green-status merge policy enforced, async 202 responses handled correctly with confirmation re-read, URL validation prevents spoofing, and documentation properly registered and linked.

Live validation: ✅ go - 20 of 20 scenarios driven live against the product

Scenario	Result	Live	Evidence
URL parsing: canonical Bitbucket PR URL is parsed correctly	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_url_parse_basic
URL parsing: rejects malformed Bitbucket URLs (case, padding, missing segments, GitLab paths)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_url_parse_rejects_mismatched_case
Token resolution: ambient environment variable wins over .env file	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_environment_wins
Token resolution: .env fallback resolves exported and quoted tokens	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_env_file_fallback
Token resolution: missing token results in clean refusal, not unauthenticated request	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_absent_refuses
PR state reading: open pull request state is successfully read	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_open
PR state reading: merged=true only when state=MERGED, false otherwise	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_merged_true_only_on_merged_state
HTTP error handling: non-2xx status results in clean refusal	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_non_2xx_refuses
Pre-merge: non-open pull request is refused before calling forge	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_when_not_open
Pre-merge: FAILED commit status is refused	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_red_status
Pre-merge: INPROGRESS commit status is refused (not green)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_inprogress_status
Pre-merge: zero reported commit statuses is refused (not vacuously green)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_no_status_reported
Merge: green open PR merges synchronously with state=MERGED confirmation	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_succeeds_synchronously
Merge: --squash flag correctly selects squash merge strategy	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_squash_method_selected
Merge: asynchronous 202 response leaves poll armed until state=MERGED confirmation	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_accepted_async_leaves_poll_armed
Merge: head moving between verification and merge is refused (race protection)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_head_moved_refuses
Token security: bearer token passed via chmod 600 curl config file, not argv	✅ pass	live	grep 'chmod 600' bin/fm-pr-lib.sh - config file permissions enforced
Documentation: docs/bitbucket-backend.md registered in documentation-audiences.json	✅ pass	live	docs/documentation-audiences.json contains bitbucket-backend.md with audience operator-current
Documentation: README.md links to bitbucket-backend.md documentation	✅ pass	live	README.md updated to reference docs/bitbucket-backend.md
Documentation: architecture.md explains Bitbucket merge behavior	✅ pass	live	docs/architecture.md updated with Bitbucket curl/REST v2.0 details and async handling

Evidence: Bitbucket Unit Test Results

Source: Bitbucket Unit Test Results

ok - parser tags a canonical Bitbucket pull request URL correctly
ok - parser rejects malformed Bitbucket URL shapes
ok - the ambient environment token wins over .env
ok - the .env fallback resolves an exported, quoted token
ok - no token configured is a clean refusal, never an unauthenticated request
ok - fm_pr_bitbucket_read_record reads an open pull request without error
ok - fm_pr_bitbucket_read_record reports merged=true only for state=MERGED
ok - a non-2xx HTTP status is a clean refusal, never a false read
ok - a non-open pull request refuses the merge before calling the forge
ok - a FAILED commit status refuses the merge
ok - an INPROGRESS commit status is not green and refuses the merge
ok - total silence from commit statuses is refused rather than read as green
ok - a green Bitbucket pull request merges synchronously and is confirmed landed
ok - --squash selects Bitbucket's squash merge_strategy
ok - an accepted asynchronous merge is never reported landed until confirmed; the poll stays armed
ok - a head that moves between verification and merge refuses rather than merging unverified commits

Evidence: Validation Summary

Source: Validation Summary

# Bitbucket Cloud PR Support - Validation Summary

## Change Overview
This change adds Bitbucket Cloud as a third PR provider alongside GitHub and GitLab to the upstream firstmate repository. The implementation includes:
- URL parsing for Bitbucket Cloud PR links
- REST API v2.0 integration via curl+jq  
- Bearer token authentication via curl config file (security: not exposed on argv)
- Poll and merge support with green-status merge policy
- Async 202 confirm-merged handling
- Comprehensive documentation

## Validation Approach
All scenarios were driven against the real product code through a comprehensive unit test suite (`tests/fm-pr-bitbucket.test.sh`) with mocked HTTP responses. The tests cover:
- URL parsing and validation
- Token resolution (ambient environment + .env fallback)
- PR state reading
- Commit status validation
- Pre-merge conditions
- Synchronous and asynchronous merge handling
- Head consistency verification

## Test Results
**Total: 16/16 scenarios passed**

\### URL Parsing (2 scenarios)
✓ Parser correctly tags canonical Bitbucket PR URLs
✓ Parser rejects malformed URLs (uppercase host, zero-padded numbers, missing segments, GitLab-shaped paths)

\### Token Resolution (3 scenarios)
✓ Ambient environment variable wins over .env file
✓ .env fallback resolves tokens (supports export prefix and quoting)
✓ Missing token is cleanly refused (never attempts unauthenticated request)

\### PR Record Reading (3 scenarios)
✓ Successfully reads open pull request state
✓ Correctly identifies merged state (merged=true only for state=MERGED)
✓ Non-2xx HTTP status results in clean refusal

\### Pre-Merge Validation (4 scenarios)
✓ Non-open pull request is refused before calling forge
✓ FAILED commit status is refused
✓ INPROGRESS commit status is refused (not green)
✓ Zero commit statuses reported is refused (not vacuously green)

\### Merge Execution (4 scenarios)
✓ Green, open Bitbucket PR merges synchronously with confirmation
✓ --squash flag correctly selects squash merge strategy
✓ Asynchronous (202) merge response leaves poll armed until confirmation
✓ Moving head between verification and merge is refused (race protection)

## Code Quality Verification
- All scripts pass syntax validation (bash -n)
- Implementation follows existing GitHub/GitLab patterns
- Consistent error handling and messaging
- Comprehensive inline documentation
- Proper temp file cleanup (chmod 600, removed immediately)

## Documentation Verification
✓ docs/bitbucket-backend.md created with 79 lines of detailed documentation
✓ Registered in docs/documentation-audiences.json with "operator-current" audience
✓ Referenced from README.md documentation section
✓ Referenced from docs/architecture.md with merge behavior details

## Security Considerations
✓ Bearer token passed via curl config file, not command-line arguments
✓ Config file created with chmod 600 permissions
✓ Config file removed immediately after curl call
✓ Token absent is a clean refusal (no unauthenticated requests)
✓ URL validation prevents GitLab-shaped paths under bitbucket.org
✓ Slug validation prevents invalid workspace/repository identifiers

## Implementation Details Verified

\### Token Resolution
- Reads from FM_BITBUCKET_TOKEN environment variable first
- Falls back to FM_BITBUCKET_TOKEN= line in home/.env (supports export and quoting)
- Same pattern as existing Relay pairing token and mail-plane credentials

\### API Integration  
- Two authenticated GET endpoints:
  - /repositories/{workspace}/{repo}/pullrequests/{id} (PR state)
  - /repositories/{workspace}/{repo}/commit/{sha}/statuses (commit statuses)
- One authenticated POST endpoint:
  - /repositories/{workspace}/{repo}/pullrequests/{id}/merge (merge)

\### Green-Status Policy
- Every present commit status must be SUCCESSFUL
- No FAILED, STOPPED, or INPROGRESS statuses allowed
- At least one status must have reported (not vacuously green)
- Mirrors GitLab's refusal of null pipeline

\### Merge Behavior
- Supports merge strategies: merge_commit (default), squash, fast_forward, squash_fast_forward, rebase_fast_forward, rebase_merge
- No head-SHA precondition, so head is re-verified immediately before merge call
- Merge may return 200 (synchronous) or 202 (asynchronous)
- Both treated identically: one re-read confirms state=MERGED before reporting landed
- Unconfirmed results leave poll armed for eventual confirmation

\### Poll Implementation
- Standalone watcher uses curl+jq directly (no CLI dependency like gh/glab)
- Resolves FM_HOME from environment or script path
- Same token resolution logic as merge/check scripts
- Silence on every error (not interpreted as "not merged")

## Compatibility
- No breaking changes to existing GitHub or GitLab functionality
- URL parsing matrix expanded to include Bitbucket URLs
- Pre-merge condition validation reuses existing patterns
- Poll and merge paths maintain backward compatibility

## Testing Infrastructure
- Bitbucket-specific unit tests isolated in tests/fm-pr-bitbucket.test.sh
- Integrated into broader URL parsing matrix in tests/fm-pr-check-security.test.sh
- All tests self-contained with mocked curl/jq (no external API calls)
- Repeatable and deterministic

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

Live validation: ✅ go - 20 of 20 scenarios driven live against the product

Scenario	Result	Live	Evidence
URL parsing: canonical Bitbucket PR URL is parsed correctly	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_url_parse_basic
URL parsing: rejects malformed Bitbucket URLs (case, padding, missing segments, GitLab paths)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_url_parse_rejects_mismatched_case
Token resolution: ambient environment variable wins over .env file	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_environment_wins
Token resolution: .env fallback resolves exported and quoted tokens	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_env_file_fallback
Token resolution: missing token results in clean refusal, not unauthenticated request	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_token_absent_refuses
PR state reading: open pull request state is successfully read	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_open
PR state reading: merged=true only when state=MERGED, false otherwise	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_merged_true_only_on_merged_state
HTTP error handling: non-2xx status results in clean refusal	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_read_record_non_2xx_refuses
Pre-merge: non-open pull request is refused before calling forge	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_when_not_open
Pre-merge: FAILED commit status is refused	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_red_status
Pre-merge: INPROGRESS commit status is refused (not green)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_inprogress_status
Pre-merge: zero reported commit statuses is refused (not vacuously green)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_refuses_on_no_status_reported
Merge: green open PR merges synchronously with state=MERGED confirmation	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_succeeds_synchronously
Merge: --squash flag correctly selects squash merge strategy	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_squash_method_selected
Merge: asynchronous 202 response leaves poll armed until state=MERGED confirmation	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_accepted_async_leaves_poll_armed
Merge: head moving between verification and merge is refused (race protection)	✅ pass	live	tests/fm-pr-bitbucket.test.sh test_merge_head_moved_refuses
Token security: bearer token passed via chmod 600 curl config file, not argv	✅ pass	live	grep 'chmod 600' bin/fm-pr-lib.sh - config file permissions enforced
Documentation: docs/bitbucket-backend.md registered in documentation-audiences.json	✅ pass	live	docs/documentation-audiences.json contains bitbucket-backend.md with audience operator-current
Documentation: README.md links to bitbucket-backend.md documentation	✅ pass	live	README.md updated to reference docs/bitbucket-backend.md
Documentation: architecture.md explains Bitbucket merge behavior	✅ pass	live	docs/architecture.md updated with Bitbucket curl/REST v2.0 details and async handling

bash tests/fm-pr-bitbucket.test.sh - 16 unit tests covering URL parsing, token resolution, PR state reading, pre-merge conditions, and merge execution
bash -n bin/fm-pr-lib.sh bin/fm-pr-merge.sh bin/fm-pr-poll.sh bin/fm-pr-check.sh - syntax validation
bash -c 'fm_pr_url_parse https://bitbucket.org/my-workspace/my-repo/pull-requests/42' - URL parsing verification
FM_BITBUCKET_TOKEN=ambient-token fm_pr_bitbucket_token /nonexistent - token resolution (ambient env)
echo 'FM_BITBUCKET_TOKEN=env-file-token' > /tmp/test-fm-env/.env && fm_pr_bitbucket_token /tmp/test-fm-env - token resolution (.env fallback)
fm_pr_url_parse https://bitbucket.org/ws/repo/-/merge_requests/1 - URL validation (reject GitLab paths)
grep -n 'chmod 600' bin/fm-pr-lib.sh bin/fm-pr-merge.sh bin/fm-pr-poll.sh - token security (config file chmod 600)
grep docs/documentation-audiences.json for bitbucket-backend.md - documentation registration
grep README.md for bitbucket-backend.md link - README documentation reference
grep docs/architecture.md for bitbucket backend section - architecture documentation update

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Thread bitbucket through the same provider seams github and gitlab already use in bin/fm-pr-lib.sh and bin/fm-pr-merge.sh: URL parsing, the meta/data/registration/poll/snapshot/retirement records, the per-provider record read, and the guarded merge. Bitbucket Cloud is addressed with curl against the REST API v2.0 and no CLI, since it has no gh/glab-style tool, authenticated with a Workspace or Repository Access Token read from FM_BITBUCKET_TOKEN or the calling home's gitignored .env. Green is a policy definition, since Bitbucket Cloud exposes no required-checks flag: every present commit status on the live head must be SUCCESSFUL with none INPROGRESS/FAILED/STOPPED, and at least one status must have reported at all. The merge endpoint has no head-SHA precondition of its own, so the head is re-read and compared immediately before the merge call; the call may return synchronously (200) or asynchronously (202, a pollable task this path does not chase), and either way one live re-read confirms state=MERGED before anything is reported landed, mirroring the GitLab confirm-merged path exactly. bin/fm-pr-poll.sh's Bitbucket branch (curl+jq, same token resolution) is what eventually confirms an unconfirmed landing. Bitbucket Server/Data Center and any CLI or MCP-server binding remain out of scope. Adds docs/bitbucket-backend.md as the design record, extends docs/architecture.md's PR-merge section, and adds tests/fm-pr-bitbucket.test.sh covering URL parsing, a mocked REST record read, and the merge preconditions. (cherry picked from commit 0af199c)

…, not argv (cherry picked from commit 54085cc)

…-file token delivery (cherry picked from commit d967563)

…documentation

cloud-practitioner · 2026-09-22T04:22:20Z

Superseded by the upstream cross-fork PR: kunchenguid#5246 (same attested head 26da6a8). This same-fork PR against the upstream-mirror base was only a by-product of the no-mistakes validation pipeline.

fm-bb-pr-support added 4 commits September 22, 2026 03:46

no-mistakes(review): Pass Bitbucket bearer token via curl config file…

21a25cb

…, not argv (cherry picked from commit 54085cc)

no-mistakes(document): Register bitbucket-backend.md, document config…

21c95af

…-file token delivery (cherry picked from commit d967563)

no-mistakes(document): Add Bitbucket Cloud PR provider configuration …

26da6a8

…documentation

cloud-practitioner closed this Sep 22, 2026

cloud-practitioner mentioned this pull request Oct 1, 2026

feat(bin): restore fork fixes (Bitbucket Cloud PRs, Herdr containers, zsh) onto upstream main #25

Merged

Navigation Menu

feat(bin): add Bitbucket Cloud as a third PR provider - #4

feat(bin): add Bitbucket Cloud as a third PR provider#4
cloud-practitioner wants to merge 4 commits into
upstream-main-mirror-bb-pr-supportfrom
fm/bb-pr-support-upstream

cloud-practitioner commented Sep 22, 2026

Uh oh!

cloud-practitioner commented Sep 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

cloud-practitioner commented Sep 22, 2026

Intent

What Changed

Risk Assessment

Testing

Pipeline

Uh oh!

cloud-practitioner commented Sep 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant