Bitbucket Pipelines

Bitbucket Pipelines is Atlassian’s integrated CI/CD solution for Bitbucket Cloud. With Gaffer, you can automatically upload and share test reports from your pipelines.

Prerequisites

• A Gaffer account with a project
• Your project’s upload token
• A Bitbucket repository with a bitbucket-pipelines.yml file

Setup

1. Add your upload token as a repository variable

1. Go to your Bitbucket repository
2. Navigate to Repository settings → Pipelines → Repository variables
3. Add a new variable:
   • Name: GAFFER_UPLOAD_TOKEN
   • Value: Your Gaffer project upload token
   • Check Secured to hide it in logs

2. Add the upload step to your pipeline

image: node:20

pipelines:
  default:
    - step:
        name: Test
        caches:
          - node
        script:
          - npm ci
          - npm test
        after-script:
          - |
            curl -X POST https://app.gaffer.sh/api/upload \
              -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
              -F "files=@test-results/junit.xml" \
              -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'"}'

Environment Variables

Bitbucket Pipelines provides these variables:

Variable	Description	Example
$BITBUCKET_COMMIT	Full commit SHA	abc123def456...
$BITBUCKET_BRANCH	Branch name	main, feature/login
$BITBUCKET_PR_ID	Pull request ID (if applicable)	42
$BITBUCKET_PR_DESTINATION_BRANCH	PR target branch	main
$BITBUCKET_REPO_SLUG	Repository slug	my-app
$BITBUCKET_BUILD_NUMBER	Build number	123

Examples

Playwright

image: mcr.microsoft.com/playwright:v1.40.0-jammy

pipelines:
  default:
    - step:
        name: Playwright Tests
        script:
          - npm ci
          - npx playwright test
        after-script:
          - |
            curl -X POST https://app.gaffer.sh/api/upload \
              -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
              -F "files=@playwright-report/index.html" \
              -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'","test_framework":"playwright","test_suite":"e2e"}'
        artifacts:
          - playwright-report/**

Jest with JUnit Reporter

image: node:20

pipelines:
  default:
    - step:
        name: Jest Tests
        caches:
          - node
        script:
          - npm ci
          - npm test -- --reporters=default --reporters=jest-junit
        after-script:
          - |
            curl -X POST https://app.gaffer.sh/api/upload \
              -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
              -F "files=@junit.xml" \
              -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'","test_framework":"jest"}'

pytest

image: python:3.11

pipelines:
  default:
    - step:
        name: pytest
        script:
          - pip install pytest pytest-html
          - pytest --html=report.html --self-contained-html
        after-script:
          - |
            curl -X POST https://app.gaffer.sh/api/upload \
              -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
              -F "files=@report.html" \
              -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'","test_framework":"pytest"}'
        artifacts:
          - report.html

Using CTRF Format

For a standardized format across all your test frameworks, consider using CTRF:

- step:
    name: Test with CTRF
    script:
      - npm ci
      # Install the CTRF reporter for your framework:
      # npm install --save-dev jest-ctrf-json-reporter
      # npm install --save-dev playwright-ctrf-json-reporter
      # npm install --save-dev vitest-ctrf-json-reporter
      - npm install --save-dev jest-ctrf-json-reporter
      - npm test -- --reporter=jest-ctrf-json-reporter
    after-script:
      - |
        curl -X POST https://app.gaffer.sh/api/upload \
          -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
          -F "files=@ctrf-report.json" \
          -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'"}'

Tip

Using after-script ensures the upload runs even when tests fail, since that’s usually when you need the report the most.

Pull Request Pipelines

For pull request pipelines, include the PR information:

pipelines:
  pull-requests:
    '**':
      - step:
          name: PR Tests
          script:
            - npm ci
            - npm test
          after-script:
            - |
              curl -X POST https://app.gaffer.sh/api/upload \
                -H "X-API-Key: $GAFFER_UPLOAD_TOKEN" \
                -F "files=@test-results/junit.xml" \
                -F 'tags={"commitSha":"'"$BITBUCKET_COMMIT"'","branch":"'"$BITBUCKET_BRANCH"'","pr":"'"$BITBUCKET_PR_ID"'"}'

Troubleshooting

Report not uploading

• Verify GAFFER_UPLOAD_TOKEN is set in repository variables
• Check the variable is marked as Secured
• Ensure after-script is used (runs even when tests fail)

401 Unauthorized

• Check your upload token starts with gfr_
• Verify the token is correctly copied (no extra spaces)

Variable not available

Some variables like $BITBUCKET_PR_ID are only available in pull request pipelines. Check the Bitbucket variables documentation for availability.

Next Steps

• CTRF Guide - Use the universal test format
• Upload API Reference - Full API documentation
• Slack Integration - Get test results in Slack

Other CI Providers: GitHub Actions · GitLab CI · CircleCI · Jenkins · Azure DevOps