Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions FORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ It is current with upstream through commit `427056c4` (2026-11-12).
| Bitbucket Cloud pull requests | Work whose pull request lives on Bitbucket Cloud is tracked like a GitHub pull request or GitLab merge request. Firstmate notices when it merges and shows its state in crew status, using your own signed-in `twg`. You still merge it yourself on Bitbucket. |
| Unanswered Bitbucket review comments | You are told when a reviewer's comment on a Bitbucket pull request goes unanswered for a time you choose. Review-bot comments count only when attached to a line of code, and you can skip named commenters. |
| Bitbucket pull request alerts | Optional alerts when a Bitbucket pull request has a merge conflict, a failed merge check, a failed build, or an unresolved review thread. Firstmate only tells you and never changes the pull request. |
| Bitbucket pull requests that answer a held decision | A decision you have put on hold can be answered automatically when its Bitbucket pull request merges, is declined or superseded, or either. You are also told once if the pull request is closed without merging. Firstmate never touches the pull request itself. |
| Open pull request with nobody watching | You are told once when a pull request is still open but nothing is monitoring it any more, for example after the no-mistakes daemon restarted, so it does not sit unnoticed. |
| Jira status that follows the work | A task's Jira work item moves to In Progress when work starts, Review when its pull request is ready, and Done when it merges. A Jira failure never blocks your work. |

Expand Down
33 changes: 28 additions & 5 deletions bin/fm-captain-hold.sh
Original file line number Diff line number Diff line change
Expand Up @@ -220,8 +220,9 @@
# or no longer a captain hold, and with a non-zero exit naming the cause when
# the question changed or the PR ended in the other terminal state.
# A `release` policy waits while the home is away, like `answer --release`, and
# a later settle-pr applies it. Only github.com PRs supported
# by the contribution observer qualify. settle-pr reads that observer's durable,
# a later settle-pr applies it. Only github.com and Bitbucket Cloud PRs supported
# by the contribution observer qualify. tasks-axi cannot link a Bitbucket PR
# through --pr, so pr-policy names its URL in the hold's title instead. settle-pr reads that observer's durable,
# validated terminal evidence, never caller-supplied state or a captain answer.
# It records forge-closed/forge-released reconciliation evidence before changing
# the task, and retries interrupted settlement without duplicating the record.
Expand Down Expand Up @@ -1840,20 +1841,42 @@ $(body_hold_set_timestamp "$(show_field_value "$1" body)")
$(resolution_record_count "$(show_field "$1" body)")"
}

show_has_link() { # <show-output> <url>: the task's structured links name this URL
local word
local -a words=()
IFS=, read -r -a words <<< "$(show_field_value "$1" links)"
for word in ${words[@]+"${words[@]}"}; do
[ "${word#*:}" != "$2" ] || return 0
done
return 1
}

command_pr_policy() {
local id=${1:-} url=${2:-} event=${3:-} action=${4:-} show dir tmp occurrence fingerprint
[ "$#" -eq 4 ] || { usage >&2; exit 2; }
[ -f "$CONFIG/hold-pr-settle" ] || fail 'config/hold-pr-settle is required'
validate_slug task-id "$id"
jq -ne --arg url "$url" '$url | test("^https://github[.]com/[A-Za-z0-9-]+/[A-Za-z0-9._-]+/pull/[1-9][0-9]*$")' >/dev/null \
|| fail 'pr-policy requires a canonical github.com PR URL'
jq -ne --arg url "$url" '$url | test("^https://github[.]com/[A-Za-z0-9-]+/[A-Za-z0-9._-]+/pull/[1-9][0-9]*$")
or test("^https://bitbucket[.]org/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/pull-requests/[1-9][0-9]*$")' >/dev/null \
|| fail 'pr-policy requires a canonical github.com or bitbucket.org PR URL'
case "$event" in merged|closed|terminal) ;; *) fail 'event must be merged, closed, or terminal' ;; esac
case "$action" in close|release) ;; *) fail 'action must be close or release' ;; esac
acquire_task_control_lock "$id"
require_tasks_axi
command_open "$id" || fail "task $id is not an open captain hold"
tasks_axi update "$id" --pr "$url" >/dev/null || fail "could not link the PR on $id"
case "$url" in
https://bitbucket.org/*)
# tasks-axi only links GitHub or Forgejo PRs through --pr, so a Bitbucket
# PR is linked by naming its URL in the title, which the backlog reads as a link.
task_show_or_fail "$id" "task $id disappeared while declaring its PR policy"
show_has_link "$show" "$url" \
|| tasks_axi update "$id" --title "$(show_field_value "$show" title) $url" >/dev/null \
|| fail "could not link the PR on $id"
;;
*) tasks_axi update "$id" --pr "$url" >/dev/null || fail "could not link the PR on $id" ;;
esac
task_show_or_fail "$id" "task $id disappeared while declaring its PR policy"
show_has_link "$show" "$url" || fail "could not link the PR on $id"
fingerprint=$(pr_hold_fingerprint "$show")
occurrence=$(( $(resolution_record_count "$(show_field "$show" body)") + 1 ))
dir="$DATA/$id"
Expand Down
17 changes: 16 additions & 1 deletion bin/fm-contributions.jq
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,29 @@ def known($input; $saved):
| [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired
| map(select(. as $pair | any($retired[]; . == $pair) | not));
# Bitbucket pull requests a fleet task recorded as its pr=, plus those already
# observed. Read only when review-thread tracking is on.
# observed. bitbucket_polled below decides which of them poll reads.
def bitbucket_known($input; $saved):
([($input.tasks // [])[] | select(.kind != "secondmate")
| select(.pr.url | bitbucket_url) | {task:.id,url:.pr.url}]
+ [$saved[] | .task as $task | .records[] | select(.url | bitbucket_url) | {task:$task,url}])
| unique_by([.task,.url])
| [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired
| map(select(. as $pair | any($retired[]; . == $pair) | not));
# The Bitbucket pull requests poll and arm --if-owned read. With thread tracking
# on, that is every one bitbucket_known names. With config/hold-pr-settle
# present, a held task's linked Bitbucket PR is read as well, and with tracking
# off it is the only one read, so its terminal state can settle the hold.
def bitbucket_polled($input; $saved; $track; $settle):
[($input.backlog.records // [])[] | select(.structured == true and .hold_bucket != null) | .id] as $held
| (bitbucket_known($input; $saved)
+ (if $settle then
[($input.backlog.records // [])[] | select(.structured == true and .hold_bucket != null) as $task
| ($task.links // [])[] | select(bitbucket_url) | {task:$task.id,url:.}]
else [] end))
| map(select($track or ($settle and (.task as $task | $held | index($task) != null))))
| unique_by([.task,.url])
| [$saved[] | .task as $task | .records[] | select(.retired != null) | {task:$task,url}] as $retired
| map(select(. as $pair | any($retired[]; . == $pair) | not));
def latest_checks:
group_by(.name) | map(sort_by([(.started_at // ""),(.id // 0)]) | last);
def projected($input; $saved; $now; $max_age):
Expand Down
26 changes: 18 additions & 8 deletions bin/fm-contributions.sh
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@
# other accepted URLs remain visibly unmeasured. A Bitbucket Cloud pull request
# is the one exception, described with the reply age below, and is never a
# coverage row.
# With config/hold-pr-settle present, a Bitbucket pull request named by a held
# task's backlog row is also observed, even with the reply age unset, so that its
# merged, declined or superseded state can settle the hold; an untracked read
# keeps no thread list and changes nothing on the forge.
# poll skips unsupported URLs without forge calls, unavailable output, wakes or
# new error stamps, and clears their legacy errors without changing observation,
# timestamps or ownership evidence.
Expand Down Expand Up @@ -201,7 +205,8 @@
# state and unanswered threads alone, so these pull requests never become
# coverage rows, counts or unmeasured entries. arm copies the ignore setting
# into the generated check, as it does the reply age, and arm --if-owned
# counts a Bitbucket pull request only while the reply age is set.
# counts a Bitbucket pull request only while the reply age is set or a held
# task's linked one can settle its hold.
# Source bodies are data, never commands.
# All mutations serialize on this home's .contributions.lock. Writes refuse
# symlinks and publish by rename. No forge writes are performed.
Expand Down Expand Up @@ -257,6 +262,8 @@ if [ -n "$REPLY_AGE" ]; then
else
REPLY_AGE=0
fi
SETTLE_HOLDS=false
[ ! -f "$CONFIG/hold-pr-settle" ] || SETTLE_HOLDS=true
case "$BUDGET" in ''|*[!0-9]*) fail 'invalid poll budget' ;; esac
[ "$BUDGET" -ge 1 ] && [ "$BUDGET" -le 25 ] || fail 'poll budget must be 1..25 seconds'
CHECK_TIMEOUT=${FM_CHECK_TIMEOUT:-30}
Expand Down Expand Up @@ -774,16 +781,15 @@ poll() {
| if . != null and (.observation.state | IN("merged","closed")) then .error == null else null end] as $final
| [(if all($final[]; .) then "settled" elif any($final[]; . != null) then "final" else "live" end), $known.url]
+ $known.tasks | @tsv' > "$TMP/known.tsv"
if [ "$TRACK_THREADS" = true ]; then
jq_lib -nr --slurpfile input "$TMP/input.json" --slurpfile saved "$TMP/saved.json" '
bitbucket_known($input[0];$saved[0])
jq_lib -nr --slurpfile input "$TMP/input.json" --slurpfile saved "$TMP/saved.json" \
--argjson track "$TRACK_THREADS" --argjson settle "$SETTLE_HOLDS" '
bitbucket_polled($input[0];$saved[0];$track;$settle)
| group_by(.url) | map({url:.[0].url,tasks:(map(.task) | unique)})
| .[] | . as $known
| [$known.tasks[] as $task | [$saved[0][] | select(.task == $task) | .records[] | select(.url == $known.url)] | first
| if . != null and (.observation.state | IN("merged","closed")) then .error == null else null end] as $final
| [(if all($final[]; .) then "settled" elif any($final[]; . != null) then "final" else "live" end), $known.url]
+ $known.tasks | @tsv' >> "$TMP/known.tsv"
fi
: > "$TMP/live.tsv"
# One pass picks the retained closures still owed to an open captain hold, so
# a home's settled history costs no process per row.
Expand Down Expand Up @@ -853,7 +859,9 @@ poll() {
| ($tracked | map(.key)) as $live
| ($due | map(.key)) as $due_keys
| $old + {checked_at:$now,error:null,
observation:($o + {absent_checks:((($old.observation.absent_checks // []) + [($old.observation.checks // [])[] | .name]) - [$o.checks[].name] | unique)}),
observation:($o + {absent_checks:((($old.observation.absent_checks // []) + [($old.observation.checks // [])[] | .name]) - [$o.checks[].name] | unique)}
# Untracked Bitbucket reads settle holds only; keep no thread list.
| if $track or (has("threads") | not) then . else .threads = [] end),
seen:((($old.seen // []) + ($events | map(.token))) | unique),
pending:((($old.pending // []) + $arrived
| map(select(.type != "unanswered" or (.thread as $k | ($live | index($k)) != null and ($due_keys | index($k)) == null))))
Expand All @@ -879,9 +887,11 @@ arm() {
acquire
if [ "${1:-}" = --if-owned ]; then
get_input; read_saved
# A Bitbucket pull request counts only while review-thread tracking is on.
# A Bitbucket pull request counts only while review-thread tracking is on or
# a held task's linked one can settle its hold.
if [ "$ERRORS" -eq 0 ] && ! jq_lib -ne --slurpfile input "$TMP/input.json" --argjson track "$TRACK_THREADS" \
--slurpfile saved "$TMP/saved.json" 'known($input[0];$saved[0]) + (if $track then bitbucket_known($input[0];$saved[0]) else [] end) | length > 0' >/dev/null; then
--argjson settle "$SETTLE_HOLDS" --slurpfile saved "$TMP/saved.json" \
'known($input[0];$saved[0]) + bitbucket_polled($input[0];$saved[0];$track;$settle) | length > 0' >/dev/null; then
return 0
fi
fi
Expand Down
4 changes: 3 additions & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -878,7 +878,9 @@ The flag is a home-local preference and is not inherited by secondmate homes.
The optional local, gitignored `config/hold-pr-settle` presence flag enables settlement of explicitly declared PR-dependent captain holds.
Create the empty flag in the owning home and use `bin/fm-captain-hold.sh pr-policy` to declare each hold's settlement policy.
The command's `--help` owns its arguments and durable record format.
The existing contribution observer applies matching GitHub merge or closure evidence, including observations retained after the worker stops.
The existing contribution observer applies matching GitHub or Bitbucket Cloud merge or closure evidence, including observations retained after the worker stops.
A Bitbucket Cloud PR linked to a held task is read for its terminal state even when `config/contributions-reply-age` is unset, and it is never merged or otherwise changed.
A declined or superseded Bitbucket PR counts as an unmerged closure.
It also reports an unmerged closure through the contribution notification channel, once for each owning task that is still an open captain hold after settlement.
A task without a captain hold gets no closure notification, so enabling the flag does not replay historical closed PRs.
No captain answer is invented, and unrelated holds remain open.
Expand Down
17 changes: 17 additions & 0 deletions docs/fork-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,23 @@ export FM_CONTRIBUTIONS_REPLY_AGE=1800
export FM_CONTRIBUTIONS_IGNORE_COMMENTERS=ci-bot
```

## Bitbucket pull requests that answer a held decision

`config/hold-pr-settle` is the upstream flag that lets a pull request event answer a decision you have put on hold.
In this fork it also works for Bitbucket Cloud pull requests, so a hold can be answered when the pull request merges, is declined or superseded, or either.
It needs no reply age: a Bitbucket pull request linked to a held decision is checked for its final state even when `config/contributions-reply-age` is unset.
Firstmate only settles the hold and never changes the pull request.

| Setting | What it controls |
| --- | --- |
| `config/hold-pr-settle` | An empty file that turns the feature on. Without it, nothing settles and no extra closure notice is sent. |

```sh
# Turn it on, then declare that a Bitbucket pull request closes the decision when it merges.
touch config/hold-pr-settle
bin/fm-captain-hold.sh pr-policy my-decision https://bitbucket.org/myworkspace/my-repo/pull-requests/7 merged close
```

## Jira status transitions

`config/jira-status-transitions` turns on Jira status follow-through for the projects it lists.
Expand Down
Loading
Loading