bb-pipelines-author-skill

Bitbucket Pipelines Author -- Skill Reference

This is the summary skill. It covers 80% of cases inline and points to references/ for full YAML examples and ecosystem-specific details.

Runtime Documentation Lookup

When this skill doesn't cover an edge case:

1. Context7 MCP (preferred) -- resolve library ID for "bitbucket pipelines", then query
2. Web fetch -- https://support.atlassian.com/bitbucket-cloud/docs/<topic>/
3. Web search -- site:support.atlassian.com bitbucket pipelines <query>

---

How to Use This Skill

Mode detection: YAML provided -> Review mode. Requirements provided -> Greenfield mode. Ambiguous -> ask.

Greenfield: Gather requirements (language, deploy targets, Docker). Walk decision trees. Load reference files for full YAML. Validate with checklist.

Review: Follow 6-step protocol. Output: summary + findings table + improved YAML + changelog.

Reference files (load on demand):

• references/architecture-patterns.md -- skeletons, triggers, clone, conditionals
• references/step-patterns.md -- caches, services, artifacts, after-script, output-variables
• references/deployment-patterns.md -- staged deploys, OIDC, runners, child/exported pipelines, imports
• references/docker-patterns.md -- build+push, BuildKit, multi-arch, layer caching, v2-to-v3
• references/review-improvement-patterns.md -- before/after patterns, build minutes playbook

---

Architecture Decisions

Pipeline Type Selection

Scenario	Type	Notes
CI on every push (catch-all)	default	Branches without a specific pipeline
Branch-specific logic	branches	Globs: 'feature/*', '{staging,production}'
PR checks	pull-requests	Matches SOURCE branch, not target
Release on tag	tags	Requires git push --tags
Manual-only or scheduled	custom	Never auto-triggered
Compound conditions, PR lifecycle, chaining	triggers + custom	Expression language, changeset functions

If both a branches pipeline and a triggers condition match, both run.

Triggers

Events: repository-push, pullrequest-created/updated/push/fulfilled/rejected/reviewer-status-updated, pipeline-completed, deployment-completed.

triggers is top-level (same level as pipelines). Only custom pipelines can be referenced. Max 20 conditions per trigger type.

triggers:
  pullrequest-fulfilled:
    - condition: >
        BITBUCKET_PR_DESTINATION_BRANCH == "main"
        && changesetInclude("src/**", "package.json")
      pipelines:
        - auto-deploy

Operators: ==, !=, &&, ||, !, (), >, >=, <, <=. Functions: glob(), changesetInclude(), changesetExclude(). No $ prefix on variables. Secured vars NOT supported. Max 1000 chars.

Size Selection

Start 1x. Bump to 2x only on OOM. Never 4x+ without benchmarking -- if <25% faster than 2x, optimize the build. Set size per-step. Memory is shared between step and services.

Size	RAM	CPU	Minutes multiplier	Plan
1x	4 GB	2 shared	1x	Free
2x	8 GB	4 shared	2x	Free
4x	16 GB	8 dedicated	4x	Standard+
8x+	32-128 GB	16-64 dedicated	8-32x	Standard+

Plan budgets: Free = 50 min/mo, Standard = 2,500, Premium = 3,500.

atlassian-ip-ranges: true routes builds through static IPs for firewall allowlisting -- requires size: 4x or greater.

Production Skeleton

Top-level key order: image -> options -> clone -> definitions -> pipelines -> triggers.

image: node:20-alpine

options:
  max-time: 30

clone:
  depth: 1

definitions:
  caches:
    pnpm:
      key:
        files:
          - pnpm-lock.yaml
      path: .pnpm-store
  steps:
    - step: &install
        name: Install
        caches:
          - pnpm
        script:
          - corepack enable
          - pnpm install --frozen-lockfile
        artifacts:
          - node_modules/**

pipelines:
  pull-requests:
    '**':
      - step: *install
      - parallel:
          fail-fast: true
          steps:
            - step:
                name: Lint
                script:
                  - corepack enable && pnpm run lint
            - step:
                name: Test
                script:
                  - corepack enable && pnpm test
  branches:
    main:
      - step: *install
      - step:
          name: Build
          script:
            - corepack enable && pnpm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy Staging
          deployment: Staging
          concurrency-group: "deploy-staging"
          oidc: true
          script:
            - ./deploy.sh staging
      - step:
          name: Deploy Production
          deployment: Production
          trigger: manual
          concurrency-group: "deploy-production"
          oidc: true
          script:
            - ./deploy.sh production

Clone, Images, and Conditionals

Clone: depth: 1 globally, depth: full per-step for git history, enabled: false for notification steps, lfs: true per-step only. skip-ssl-verify: true is step-level, self-hosted only.

Image pinning: Always specific tags (node:20-alpine). Never :latest, :current, :lts, untagged. run-as-user: 1000 -- UID must exist in image.

Monorepo: condition.changesets.includePaths. Cannot mix includePaths/excludePaths on same step.

${{ }}: Parse-time injection. Secured variables NOT supported (resolve to empty).

Pipeline Imports: Same-repo (no export: true) or cross-repo (export: true). Max 50 sources. Formats: {filepath}, {slug}:{branch}, {slug}:{branch}:{filepath}.

-> Full patterns: references/architecture-patterns.md -> Look up: "dynamic-pipelines" or "pipeline-imports" on support.atlassian.com

Anti-Patterns

• options: docker: true globally -- use services: [docker] per-step (1 GB wasted per non-Docker step)
• No max-time -- default 120 min burns credits on stuck builds
• Mutable image tags -- pin versions (applies to both image: and service/DinD images)
• Unquoted globs -- feature/*: fails; use 'feature/*':

---

Step Patterns

Shape: build -> parallel test -> deploy. Use artifacts: download: false on non-consuming steps. Use key.files caches tied to lockfiles.

Cache Key Patterns

Ecosystem	key.files	path
Node (pnpm)	pnpm-lock.yaml	.pnpm-store
Node (npm)	package-lock.json	.npm-cache
Python (uv)	uv.lock	.uv-cache
Python (Poetry)	poetry.lock	.venv
Go	go.sum	/root/go/pkg/mod
Java (Gradle)	build.gradle, gradle.lockfile	~/.gradle/caches
Ruby	Gemfile.lock	vendor/bundle

Default time-based caches expire after 7 days. Always use key.files for correct invalidation.

definitions:
  caches:
    pnpm-store:
      key:
        files:
          - pnpm-lock.yaml
      path: .pnpm-store

Artifacts, Services, and Failure Handling

Artifacts: Negation globs ("!dist/**/*.map"). Named artifacts with selective download:. capture-on: fail for debug logs. 1 GB/group, 14-day expiry. Parallel steps cannot consume each other's.

Services: Shared on localhost. 4 GB total (1x). Max 5 (excl. docker). Always health-check wait before connecting.

after-script: Runs regardless of outcome. $BITBUCKET_EXIT_CODE only here.

output-variables: Write to $BITBUCKET_PIPELINES_VARIABLES_PATH. 50 max, 100 KB combined.

Scenario	Config
Core tests	fail (default)
Flaky E2E	on-fail: { strategy: retry, maxRetryCount: 2 }
Optional lint	on-fail: { strategy: ignore }
CI parallel group	fail-fast: true
Production deploy	trigger: manual (cannot be first step)
Deploy locking	concurrency-group: "deploy-production"

on-fail at step/parallel/stage level; step overrides parent. maxRetryCount: 1-10. Artifacts expire 14 days -- rebuild in manual steps if needed.

-> Full patterns: references/step-patterns.md

Anti-Patterns

• No artifacts: download: false on non-consuming steps
• Caching node_modules directly -- cache package manager store with lockfile key
• Secrets in --build-arg -- use --secret mount
• || true swallowing failures -- use on-fail: { strategy: ignore } or retry
• No health-check waits -- race condition on service startup

---

Deployment & Orchestration

Stage vs No Stage

Use stages for manual gates on step groups, deployment over multiple steps, group-level condition/on-fail. Skip when linear or needing parallel inside (stages CANNOT contain parallel groups). Stages cannot contain manual/conditional steps (stage itself can be). Max: Free 10, Standard/Premium 100 steps/stage.

OIDC (AWS / GCP)

Set oidc: true per step. Write $BITBUCKET_STEP_OIDC_TOKEN to file. JWT claims: sub, aud, repositoryUuid, branchName, deploymentEnvironment.

- step:
    oidc: true
    image: amazon/aws-cli:2.15.30
    script:
      - export AWS_REGION=eu-west-1
      - export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/bitbucket-deploy
      - export AWS_WEB_IDENTITY_TOKEN_FILE=$(pwd)/web-identity-token
      - echo $BITBUCKET_STEP_OIDC_TOKEN > $AWS_WEB_IDENTITY_TOKEN_FILE
      - aws s3 sync dist/ s3://myapp-production/

Custom audiences (object form): max 10 per step, 150 chars each. Per-step overrides global options.oidc.audiences.

OIDC without oidc: true: $BITBUCKET_STEP_OIDC_TOKEN is silently empty. Auth fails with no clear error. [CRIT]

environment vs deployment

environment = env-scoped vars only, no lock. deployment = full tracking, dashboard, concurrency control. Use deployment only on steps that mutate infrastructure.

Self-Hosted Runners

Labels: self.hosted (required, first), linux, linux.shell, linux.arm64 (needs atlassian/default-image:4+), windows, macos. Self-hosted size caps at 8x; shell runners ignore size. No matching runner = immediate failure. oidc defaults true on self-hosted. Runner v5+ supports volume mounts and S3/GCS storage backends.

Pipeline Reuse Decision Tree

Need	Solution
Same-file reuse	YAML anchors (definitions.steps with &anchor/*anchor)
Parameterized (same repo)	Child pipelines (input-variables, max 20)
Cross-repo sharing	Exported pipelines (export: true) or definitions.imports
Named version-pinned sources	definitions.imports (max 50 per file)
Deployment tracking	Anchors or exported -- child pipelines lack deployment

Child pipeline constraints: No script, caches, services, artifacts, deployment, oidc. No secured vars in input-variables. Max 20 input-variables.

Custom Pipelines with UI Variables

Use - variables: with allowed-values for dropdowns, plain name/default for text input. Renders UI pickers in Bitbucket.

-> Full patterns: references/deployment-patterns.md -> Look up: "configure-oidc-with-bitbucket" on support.atlassian.com

Anti-Patterns

• Hardcoded AWS credentials -- use oidc: true
• deployment on read-only steps -- use environment instead
• Missing concurrency-group on deploy steps
• Mixed credential strategies -- all environments should use OIDC

---

Docker & Container Builds

v2 vs v3 Decision

v2 (default) for simple docker build + push and pipe-only steps. v3 for docker buildx/multi-arch, --privileged, RUN --mount=type=ssh (silently fails on v2). Start v2; switch only when needed. v2 blocks: --cap-add, --device, --mount, --privileged, --volume, and others. Port 29418 reserved.

v2 to v3 Migration

1. Add runtime: { cloud: { version: "3" } } per-step (not globally)
2. Set image: docker:28-cli (CLI not auto-mounted in v3)
3. Replace caches: [docker] with --cache-from/--cache-to
4. Remove export DOCKER_BUILDKIT=1 (already default)
5. Test volume mounts work correctly
6. Verify pipe-only steps still work on v2

Memory Budget

script_memory = size_total - docker_memory - other_services_memory. 1x+Docker = 2048 MB for script. 2x+Docker = 6144 MB. OOM? Increase size or reduce service memory. Max 5 services (excl. docker).

BuildKit Secrets & Layer Caching

Never --build-arg with secrets -- use --secret mount + RUN --mount=type=secret in Dockerfile. Tag with $BITBUCKET_COMMIT, never :latest. BuildKit is default -- never export DOCKER_BUILDKIT=1.

Layer caching: Predefined docker cache does NOT cache BuildKit layers. Use --cache-from type=registry,ref=... / --cache-to type=inline, or S3-based on v3.

Pipes: Pre-packaged Docker containers. Cache with services: [docker] + caches: [docker]. Cloud-only (not Bitbucket Data Center).

-> Full patterns: references/docker-patterns.md -> Look up: "docker-in-bitbucket-pipelines" on support.atlassian.com

Anti-Patterns

• RUN --mount=type=ssh on v2 -- silently fails; use v3
• caches: [docker] with BuildKit -- does not cache BuildKit layers
• export DOCKER_BUILDKIT=1 -- already default; remove
• Global runtime: v3 -- v3 doesn't auto-mount CLI; set per-step with docker:28-cli
• --build-arg BUILDKIT_INLINE_CACHE=1 with explicit cache flags -- redundant
• caches: [docker] in steps with both pipes and own builds -- pipe images fill the cache; split into separate steps

---

Reviewing Existing Pipelines

6-Step Review Protocol

1. Parse -- Steps (max 100), pipeline types, services/caches, anchors
2. Security -- Hardcoded secrets? :latest? Missing OIDC? --build-arg? Secured in ${{ }}?
3. Performance -- Caches with key.files? artifacts: download: false? clone: depth: 1?
4. Cost -- size justified? Parallel = same minutes, less wall-clock
5. Reliability -- on-fail? max-time? after-script? Health-check waits? concurrency-group?
6. Maintainability -- Anchors for repeated steps? Monorepo changesets?

Severity Calibration

CRIT (must fix): Hardcoded keys, --build-arg secrets, secured var in ${{ }}/child pipeline, wrong deployment order, manual first step, mixed OIDC/long-lived keys, mutable image tags, --ssh/--mount=type=ssh on v2 (silent fail), $BITBUCKET_STEP_OIDC_TOKEN without oidc: true (silent empty), || true/|| exit 0 swallowing test/deploy failures (exception: after-script cleanup commands where non-zero exit is expected).

WARN (should fix): Missing concurrency-group, 2x on lint, no fail-fast, bad cache keys, global docker: true, global runtime: v3 without CLI image, missing max-time/after-script/clone: depth/on-fail: retry, install without cache, redundant BUILDKIT_INLINE_CACHE=1, docker cache mixed with own builds.

INFO (nice to have): Non-alpine images, no anchors, expression near 1000-char limit.

Review Output Format

Output: ## Summary (one line) -> ## Findings (table: #, Severity, Location, Issue, Fix) -> ## Improved Pipeline (complete YAML) -> ## Changelog (bulleted, prefixed by severity). Do NOT add features the user didn't have. Always output complete YAML.

Top Improvement Patterns

1. Fat step -> parallel fan-out -- split build+lint+test into parallel
2. Hardcoded keys -> OIDC -- oidc: true with short-lived tokens
3. Repeated installs -> cache + artifacts -- single install, lockfile-keyed cache
4. No Docker caching -> BuildKit registry cache -- --cache-from/--cache-to
5. Duplicated steps -> YAML anchors -- definitions.steps with &anchor/*anchor
6. No error handling -> after-script + on-fail + health checks
7. || true on tests -> on-fail: { strategy: ignore } or { strategy: retry }

-> Full patterns: references/review-improvement-patterns.md

---

Validation & Gotchas

Pre-Commit Checklist (16 items)

Structure:

• Valid YAML (no tabs, 2-space indent)
• pipelines: key exists
• Step count <= 100 per pipeline
• trigger: manual is never first step

Security:

• No hardcoded credentials -- all secrets via $VARIABLE
• No --build-arg with secrets -- use --secret mount
• No secured vars in ${{ }} templates
• No secured vars in child pipeline input-variables
• oidc: true set on every step using $BITBUCKET_STEP_OIDC_TOKEN

Performance:

• Single install, consume via artifacts
• Caches use key.files tied to lockfiles
• size: 2x+ justified (lint/notify/deploy = 1x)

Reliability:

• Deploy steps have concurrency-group
• No || true on important commands
• Service health-check waits for databases
• max-time set (never rely on 120-min default)

Security Checklist

• OIDC for cloud credentials, not long-lived keys
• Docker secrets via --secret, never --build-arg
• No literal credentials in script:
• All images pinned (both image: and services); pipes version-pinned
• --privileged only on v3 steps; consistent credential strategy across envs
• Production deploys use trigger: manual; OIDC audiences scoped

YAML Traps

Tabs forbidden (use 2 spaces). Quote booleans as branch names ('true':). Quote colons in names ('Build: Production'). | for bash blocks, > for PowerShell. Anchor names: no [ ] { } ,. <<: replaces script: lists, never appends. Use / in paths, never \.

Variable Gotchas

${{ }} = parse time (no secured/output vars). $VAR = runtime. Precedence: Pipeline > Deployment > Repository > Workspace > Default. $BITBUCKET_BRANCH null on detached HEAD. $BITBUCKET_EXIT_CODE only in after-script. Windows: $env:VAR. Never name a variable PATH. Value limit: 120K chars. Output-variables: 50 max, 100 KB. Expression: 1000 chars max, no $ prefix.

Common Errors

Symptom	Fix
"Step is not valid"	Indent properties under - step:
"Pipeline could not be parsed"	Quote globs: 'feature/*'
trigger: manual first step	Add automated step before
docker: command not found (v3)	image: docker:28-cli
OOM killed	Size up or reduce service memory
Cache miss every run	Match key.files to actual lockfiles
Connection refused	Add health-check wait loop
Pipeline runs twice	Use branches or triggers, not both
Deployment order invalid	Test -> Staging -> Production
Artifacts missing	Check producer globs; check download: false
Pipeline not triggered (bulk)	Push <=5 new refs; or use API

Critical Gotchas Quick Reference

1. Secured vars in ${{ }} -- empty at parse time
2. Secured vars to child pipelines -- build fails
3. trigger: manual first step -- pipeline won't start
4. --build-arg with secrets -- baked into layer history
5. RUN --mount=type=ssh on v2 -- silently fails
6. $BITBUCKET_STEP_OIDC_TOKEN without oidc: true -- token is silently empty
7. PATH as pipeline variable -- breaks all commands
8. Bulk push >5 new refs -- triggers zero pipelines; push in batches of 5 or use API
9. IPv4 only -- bind to 0.0.0.0, never ::1
10. docker cache + BuildKit -- doesn't cache BuildKit layers
11. Parallel doesn't save minutes -- 3 parallel 2x = 6x billed

Quick Wins

Action	Savings per run
clone: depth: 1 globally	5-15 sec/step
artifacts: download: false on non-consuming steps	5-30 sec/step
node:20-alpine over node:20	10-30 sec/step
Lockfile-keyed cache	30-120 sec/cached step
Downsize 2x lint steps to 1x	50% minutes on those steps
condition.changesets in monorepo	Skip entire steps
max-time: 15 (from default 120)	Up to 105 min on stuck builds
Per-step services: [docker] over global docker: true	~512 MB freed/non-Docker step

Platform Notes

Cloud-only (no Data Center). Manual steps always block. No Atlassian-hosted Windows runners. IPv4 only. Storage: Free 1 GB, Standard 5 GB, Premium 10 GB.

Limits Quick Reference

Resource	Free	Standard/Premium
Build minutes/month	50	2,500 / 3,500
Steps per pipeline	100	100
Steps per stage	10	100
Concurrent steps	10	600
Import sources per file	50	50
Child pipeline input-variables	20	20
Output-variables per pipeline	50	50
OIDC audiences per step	10	10
Artifact expiry	14 days	14 days
Max step time	720 min	720 min
Storage (LFS/artifacts/caches)	1 GB	5 / 10 GB

-> Look up: "bitbucket-pipelines-configuration-reference" on support.atlassian.com for any property. -> Look up: "variables-and-secrets" for the complete variable list. -> Look up: "limitations-of-bitbucket-pipelines" for platform limits.