Skip to content

Bitbucket Pipelines

This project includes a Bitbucket Pipelines template to run Agronomist using Bitbucket Cloud Pipelines.

Available CLI Options

When running Agronomist in Bitbucket Pipelines, you can use these CLI options (either directly in the script or mapped via variables):

  • --bitbucket-token Bitbucket token for API calls and PR creation.
  • --bitbucket-username Optional Bitbucket username for App Password Basic Auth. When omitted, Agronomist uses Bearer authentication for Repository Access Tokens.
  • --root Root directory to scan. Default: .
  • --include Glob patterns to include. Can be specified multiple times.
  • --exclude Glob patterns to exclude. Can be specified multiple times.
  • --json JSON report file name. Required for multi-PR workflows.
  • --markdown Markdown report file (optional).
  • --bitbucket-base-url Bitbucket API base URL. Default: https://api.bitbucket.org/2.0
  • --resolver Version resolver strategy: git, github, bitbucket, or auto. Default: git
  • --config Path to configuration file. Default: .agronomist.yaml
  • --validate-token Validate API token before processing.

Requirements

  • Bitbucket Cloud Pipelines enabled for the repository.
  • Bitbucket token stored as a secured repository or workspace variable.
  • git, curl, and jq installed in the pipeline image.

Variables

  • BITBUCKET_TOKEN Token used by Agronomist for Bitbucket API calls and PR creation.
  • BITBUCKET_WORKSPACE Workspace slug. Provided automatically by Bitbucket Pipelines.
  • BITBUCKET_REPO_SLUG Repository slug. Provided automatically by Bitbucket Pipelines.
  • AGRONOMIST_VERSION Agronomist release or package version (e.g. 1.2.10).
  • AGRONOMIST_ROOT Root directory to scan. Default: .
  • AGRONOMIST_RESOLVER Resolver strategy: git, github, bitbucket, or auto. Default: auto.
  • AGRONOMIST_CONFIG Path to configuration file (supports category rules and blacklist filters). Default: .agronomist.yaml.
  • PR_BODY Pull Request description. Default: Updates generated by Agronomist..
  • PR_TARGET_BRANCH Target branch for PR. Default: main or $BITBUCKET_BRANCH.

Pipeline overview

  • agronomist-update custom pipeline runs Agronomist, applies changes, and automatically creates one Pull Request per updated module if updates are found.
  • Manual and scheduled runs: Bitbucket custom pipelines are triggered manually or from a repository schedule.
  • Dynamic branch naming: Each PR branch is named agronomist/update-<base-module>-<hash8>, where <hash8> is the first 8 characters of the SHA-256 hash of the full module ID. This keeps branch names short and guarantees uniqueness across files.
  • Git configuration: The template configures Git to use BITBUCKET_TOKEN with the x-token-auth user for HTTPS access to private repositories.
  • PR cleanup: Deletes existing remote branch before pushing to avoid conflicts when re-running the pipeline.
  • Report handling: Generates report.json during the pipeline to extract per-module file lists. The report is consumed in-pipeline and is not committed to the repository.

Example

See examples/bitbucket-pipelines.yml and examples/bitbucket/create_pr.sh for the full pipeline and helper script.

image: python:3.12-slim

pipelines:
  custom:
    agronomist-update:
      - step:
          name: Run Agronomist update
          script:
            - apt-get update -qq && apt-get install -y -qq git curl jq ca-certificates
            - pip install -q "agronomist==${AGRONOMIST_VERSION}"
            - git config user.name "agronomist-bot"
            - git config user.email "agronomist@bot.local"
            - git config --global url."https://x-token-auth:${BITBUCKET_TOKEN}@bitbucket.org/".insteadOf "https://bitbucket.org/"
            - agronomist update --root "${AGRONOMIST_ROOT:-.}" --resolver "${AGRONOMIST_RESOLVER:-auto}" --config "${AGRONOMIST_CONFIG:-.agronomist.yaml}" --json report.json --bitbucket-token "$BITBUCKET_TOKEN"
            - bash examples/bitbucket/create_pr.sh

Authentication notes

Agronomist supports two Bitbucket Cloud authentication modes:

  • Repository Access Token (Bearer): Set BITBUCKET_TOKEN or pass --bitbucket-token. Do not set --bitbucket-username; Agronomist sends the token as a Bearer token.
  • App Password (Basic): Pass both --bitbucket-username and --bitbucket-token. Agronomist sends Basic authentication using username + token.

The helper script uses Bitbucket's HTTPS Git convention for pushes and PR creation:

git config --global url."https://x-token-auth:${BITBUCKET_TOKEN}@bitbucket.org/".insteadOf "https://bitbucket.org/"
curl -u "x-token-auth:${BITBUCKET_TOKEN}" "https://api.bitbucket.org/2.0/repositories/${BITBUCKET_WORKSPACE}/${BITBUCKET_REPO_SLUG}/pullrequests"

Store BITBUCKET_TOKEN as a secured Bitbucket variable. Never hardcode tokens in the pipeline file.

Limitations

  • Bitbucket support is Cloud-only. Bitbucket Server/Data Center support is a future TODO.
  • The template creates one PR per updated module and assumes report.json contains file lists for each update.
  • The helper requires jq; install it in the image before running the script.
  • If a PR already exists for a recreated branch, the Bitbucket API call may fail and the script logs the failure without exposing secrets.