bitbucket

Bitbucket

Overview

Automate and extend Bitbucket Cloud — Atlassian's Git platform with built-in CI/CD. This skill covers repository management, Bitbucket Pipelines configuration, pull request workflows, branch permissions, deployment environments, the REST API 2.0, webhooks, Jira integration, and merge checks.

Instructions

Step 1: Authentication

// Bitbucket Cloud uses App Passwords (basic auth) or OAuth 2.0.
// Create an App Password at: https://bitbucket.org/account/settings/app-passwords/

const BB_BASE = "https://api.bitbucket.org/2.0";
const AUTH = Buffer.from(
  `${process.env.BB_USERNAME}:${process.env.BB_APP_PASSWORD}`
).toString("base64");

async function bb(method: string, path: string, body?: any) {
  const res = await fetch(`${BB_BASE}${path}`, {
    method,
    headers: {
      Authorization: `Basic ${AUTH}`,
      "Content-Type": "application/json",
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(`BB ${method} ${path}: ${res.status} ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

Step 2: Repositories

// Create a repository
const repo = await bb("POST", `/repositories/my-workspace/my-new-repo`, {
  scm: "git",
  is_private: true,
  description: "Backend API service",
  project: { key: "ENG" },
  mainbranch: { name: "main" },
  fork_policy: "no_public_forks",
});

// List, get details, list branches
const repos = await bb("GET", `/repositories/my-workspace?q=project.key="ENG"&sort=-updated_on&pagelen=25`);
const repoInfo = await bb("GET", `/repositories/my-workspace/my-repo`);
const branches = await bb("GET", `/repositories/my-workspace/my-repo/refs/branches?sort=-target.date&pagelen=25`);

// Get file content / browse tree
const fileContent = await fetch(
  `${BB_BASE}/repositories/my-workspace/my-repo/src/main/README.md`,
  { headers: { Authorization: `Basic ${AUTH}` } }
).then(r => r.text());

Step 3: Pull Requests

// Create a pull request (Jira keys like ENG-142 in description auto-link)
const pr = await bb("POST", `/repositories/my-workspace/my-repo/pullrequests`, {
  title: "feat: add user authentication module",
  description: "Implements OAuth2 login.\n\nCloses ENG-142",
  source: { branch: { name: "feature/auth" } },
  destination: { branch: { name: "main" } },
  close_source_branch: true,
  reviewers: [{ account_id: "5f1234abc..." }],
});

// List, approve, request changes
const openPRs = await bb("GET", `/repositories/my-workspace/my-repo/pullrequests?state=OPEN&pagelen=50`);
await bb("POST", `/repositories/my-workspace/my-repo/pullrequests/${pr.id}/approve`);
await bb("POST", `/repositories/my-workspace/my-repo/pullrequests/${pr.id}/request-changes`);

// Comments (general and inline on a specific file/line)
await bb("POST", `/repositories/my-workspace/my-repo/pullrequests/${pr.id}/comments`, {
  content: { raw: "Looks good! One suggestion on the token expiry logic." },
});
await bb("POST", `/repositories/my-workspace/my-repo/pullrequests/${pr.id}/comments`, {
  content: { raw: "Use `crypto.timingSafeEqual` here to prevent timing attacks." },
  inline: { path: "src/auth/jwt.ts", to: 42 },
});

// Merge: "merge_commit" | "squash" | "fast_forward"
await bb("POST", `/repositories/my-workspace/my-repo/pullrequests/${pr.id}/merge`, {
  merge_strategy: "squash",
  message: "feat: add user authentication module (#142)",
  close_source_branch: true,
});