title: Create Bitbucket Pull Request description: Propose a ticket-prefixed branch name, commit the current changes with a Securitize-format message, push, and open a Bitbucket PR using the standard template with default reviewers minus the author. triggers: - open a Bitbucket PR - create a pull request for this ticket - push my changes and open the PR - make a PR on Bitbucket prerequisites: - A local clone of a securitize_dev/* Bitbucket repository with the changes to ship (uncommitted or already committed on a non-protected branch) - Bitbucket MCP available (no fallback — the workflow halts if not configured, to avoid publishing malformed PRs). Setup instructions in wiki/ai-tooling/mcp-and-ai-tooling.md under the Atlassian Rovo MCP section (specifically the API-token entry that exposes Bitbucket). - git configured with the developer's identity (git config user.email / user.name) affects: - The current Bitbucket repository (new branch pushed, new PR opened) related: - wiki/engineering-practices/code-reviews.md - wiki/organization/jira-boards.md - wiki/ai-tooling/mcp-and-ai-tooling.md last_updated: 2026-05-12

Create Bitbucket Pull Request¶

TL;DR — Validates the current branch is not protected, proposes a ticket-prefixed branch name when needed, commits with the [TICKET] description format, pushes, and opens a Bitbucket PR against dev (default) using the Securitize PR template, preserving default reviewers and excluding the PR author. Not for ops-scripts config changes — those use configure-service-configmap.

Overview¶

This workflow operates on the repository the developer is currently working in ($PWD). It does not clone anything — it assumes a local working tree with changes ready to ship. Branch naming, commit format, target branch, and reviewer handling follow Securitize conventions encoded here; the approval rules, ownership model, and Jira project identifiers live in the wiki and are linked, not restated.

Scope: staging-branch work (typically dev). The workflow will create a PR against any target branch the developer explicitly requests, but it defaults to dev and never commits or pushes directly to protected branches (see Step 2). Release workflows (e.g. dev → rc → master) and hotfix coordination are out of scope.

Bitbucket MCP is required — there is no manual-URL fallback. A PR opened through the browser loses the automated reviewer filtering (Bitbucket rejects a PR that lists the author as a reviewer), so the workflow halts early if the MCP is not available rather than producing a PR that needs manual cleanup.

Inputs¶

ticket number (required) — the Jira issue key, e.g. ON-1234, CTD-295, ISR2-42. The project prefix is whatever appears in the developer's Jira board; the canonical list lives in wiki/organization/jira-boards.md.
target branch (optional) — defaults to dev. Override only when the developer explicitly requests a different base (e.g. a long-running feature branch).
draft status (asked at Step 4) — Draft PR or Ready for Code Review. Defaults to Ready for Code Review if the developer does not answer.

Steps¶

1. Probe Bitbucket MCP and read the repo coordinates¶

Before any git operation, confirm the Bitbucket MCP is reachable. Call any read-only tool the MCP exposes (e.g., a repository-metadata fetch) using the workspace and repo slug derived below. A successful response means the MCP is configured. The agent maps "fetch repository metadata" onto whichever tool name the active MCP uses — different Bitbucket MCPs name the same operation differently; do not assume one specific tool name.

If the call fails or the tool is not available, stop and point the developer to wiki/ai-tooling/mcp-and-ai-tooling.md — specifically the Atlassian Rovo MCP section, which documents the two registration entries, the required Atlassian API token for Bitbucket, and the verification call. Do not attempt a browser-URL fallback (see Overview for the reason).

Extract workspace and repo_slug from the active remote:

git -C "$PWD" remote get-url origin

Parse the output — both SSH (git@bitbucket.org:{workspace}/{repo_slug}.git) and HTTPS (https://bitbucket.org/{workspace}/{repo_slug}.git) forms are valid. If the remote is not on bitbucket.org, stop — this workflow only covers Bitbucket Cloud.

2. Enforce branch protection and propose a compliant branch¶

Read the current branch:

git -C "$PWD" rev-parse --abbrev-ref HEAD

Never commit or push on dev, rc, or master. The branch name must start with the ticket key (e.g. ON-1234-fix-auth).

On a protected branch (dev, rc, master) → the workflow must create a new branch. Do not stash or force-move commits the developer has already made on the protected branch; instead, ask the developer to confirm you can branch off the current HEAD, then proceed.
On a non-protected branch that does not start with the ticket key → inspect the changes:
```
git -C "$PWD" status --short
git -C "$PWD" diff
```
Propose a branch name of the form {TICKET}-{kebab-case-summary} (e.g. ON-1234-fix-auth-payload) derived from the diff. Wait for explicit developer confirmation before running git checkout -b.
On a compliant branch already → skip the rename and continue.

Do not rename a branch that has already been pushed to Bitbucket — create a new one and move the commits over, or ask the developer how to proceed.

3. Stage and commit the pending changes¶

If there is nothing to commit (git status --porcelain is empty) and the branch is already ahead of origin, skip to Step 4.

Otherwise, analyze the pending changes and propose a commit message in the exact form:

[{TICKET}] {Brief description}

Example: [ON-1234] Fix user authentication payload.

Hard constraints: - Do not append Co-authored-by, Generated-by, or any AI-attribution trailers. This workflow is caller-agnostic; the caller's default commit trailer must be suppressed for the commit created here. - Do not use git commit --amend on a commit that has already been pushed.

Present the proposed message and wait for developer confirmation, then:

cd "$PWD"
git add -A       # or specific paths if the developer restricts scope
git commit -m "[{TICKET}] {Brief description}"

4. Collect PR metadata¶

Ask the developer, in order:

Draft or Ready for Code Review? — passed to the create-PR call as the draft flag. Default: Ready for Code Review (draft: false) if the developer does not answer or replies non-committally (e.g. "whatever", "you choose"). Only set draft: true when the developer explicitly asks for a draft.
Target branch? — confirm the default dev or accept an override.

Draft the PR description using the template below (Step 5). Present it to the developer and wait for confirmation or edits before creating the PR.

5. PR description template (mandatory)¶

The description MUST follow this exact Markdown structure. Fill each section from the diff, the ticket, or explicit developer input — do not invent content, and do not restate the Jira ticket description in the ## Description section (that section is for technical decisions, not functional summary).

## Description
_Brief PR description about technical decisions like refactors, naming conventions, tech diagrams, etc. Ticket description should not be repeated here._

## PR dependencies
_Any PR dependency? (e.g. ops-scripts PR, any API PR to be merged first, etc.) — write "None" if there are no dependencies._

## Screenshots/videos
_Screenshots/videos from ticket scenarios, or "N/A" for backend-only changes._

## Checklist
- Ticket number on the PR's title?
- All scenarios on the acceptance criteria have corresponding tests?
- Setup steps to test the changes locally?: if those are needed, then list them please.

The PR title must start with the ticket key and match the commit message where possible (e.g. [ON-1234] Fix user authentication payload).

6. Push the branch¶

cd "$PWD"
git push -u origin "$(git rev-parse --abbrev-ref HEAD)"

If the push is rejected because the branch already exists on the remote, ask the developer whether to force-push (only acceptable on their own feature branch) or to create a new branch. Do not force-push on their behalf without explicit confirmation.

7. Resolve default reviewers and exclude the author¶

Bitbucket rejects pull-request creation if the author is included in the reviewers array.

Identify the author:

git -C "$PWD" config user.email
git -C "$PWD" config user.name

Call the Bitbucket MCP's effective-default-reviewers operation for the repo (using the workspace and repo slug from Step 1). The agent maps this onto whichever tool name the active MCP exposes for "look up the configured default reviewers for this repository".
From the response, build the reviewers array — each entry containing the reviewer's UUID — excluding the reviewer whose account ID, nickname, display name, or email matches the author. If the match is ambiguous, ask the developer to confirm which reviewer to drop before proceeding.

If the active MCP does not expose a separate default-reviewers operation (some MCPs resolve defaults automatically inside their create-PR call), skip steps 2–3 and trust the MCP's create-PR call to apply the repo's configured defaults. Verify after creation (Verification section) that the author is not in the resulting reviewer list.

For the reasoning behind default reviewers (team ownership via Bitbucket project, no CODEOWNERS), see wiki/engineering-practices/code-reviews.md → Ownership model. This workflow does not choose reviewers — it preserves whatever Bitbucket resolves for the repo.

8. Final confirmation¶

Present a single summary to the developer:

Source branch → target branch
PR title
PR description (rendered block)
Draft status
Reviewers retained (names) and the one excluded because they are the author

Wait for explicit confirmation. Do not proceed on an implicit signal.

9. Create the PR¶

Call the Bitbucket MCP's create-pull-request operation with the following inputs. The agent maps the parameter names below onto whatever shape the active MCP expects (e.g., workspace/repo_slug vs workspaceId/repoId):

workspace and repo slug — from Step 1
source branch — the pushed branch from Step 6
destination branch — the target from Step 4 (default dev)
title — from Step 5
description — from Step 5
draft flag — from Step 4
reviewers — the filtered array from Step 7 (omit if Step 7 was skipped per its fallback)

Return the PR URL to the developer.

Verification¶

git log origin/{source-branch} -1 on the remote matches the local HEAD.
The PR exists on https://bitbucket.org/{workspace}/{repo_slug}/pull-requests/... with the expected title, description, target, draft status, and reviewer list.
The author does not appear in the reviewer list.
The PR title starts with [{TICKET}].

For approval expectations after the PR is open (1–2 approvals for dev, minimum 1 for master), see wiki/engineering-practices/code-reviews.md → Approval rules.

Rollback¶

Before push (Steps 1–5): git reset --soft HEAD~1 discards the new commit and keeps the working tree; git checkout - returns to the previous branch; delete the new local branch with git branch -D {branch} if it was created in Step 2.
After push, before PR creation (Step 6 done, Step 9 not yet): delete the remote branch with git push origin --delete {branch}.
After PR creation (Step 9 done): decline the PR via the Bitbucket MCP's decline-PR operation (or via the Bitbucket web UI), and delete the remote branch if no other work depends on it.

Tags¶

workflow #bitbucket #pull-request #git¶