CI/CD Integration

Run Bruno collections in your CI/CD pipelines with the Bruno CLI

Overview

Bruno CLI enables you to automate API testing in your continuous integration and deployment workflows. Run your collections in GitHub Actions, GitLab CI, Jenkins, or any other CI/CD platform.

Installation

Install Bruno CLI in your CI environment:

npm

npm install -g @usebruno/cli

Basic Usage

1. Navigate to your collection

   The Bruno CLI needs to be run from your collection directory.

   cd path/to/your-collection
   
2. Run all requests

   Execute all requests in your collection:

   bru run
   
3. Check exit codes

   Bruno CLI returns different exit codes for scripting:

   • 0 - Execution successful
   • 1 - Assertion, test, or request failed
   • 2 - Output directory doesn’t exist
   • 3 - Infinite loop detected
   • 4 - Not in collection root directory
   • 5 - Input file doesn’t exist
   • 6 - Environment doesn’t exist
   • 255 - Other error occurred

Running Specific Tests

Single Request

Run a specific request file:

bru run request.bru

Folder of Requests

Run all requests in a subfolder:

bru run folder

With Environment

Specify an environment for your tests:

bru run folder --env Prod

Tests Only

Run only requests that have tests defined:

bru run --tests-only

Output and Reporting

JSON Output

Save test results as JSON:

bru run --output results.json

JUnit Report

Generate JUnit XML for CI integration:

bru run --output junit.xml --format junit

Multiple Reporters

Generate multiple report formats:

bru run \
  --reporter-json results.json \
  --reporter-junit junit.xml \
  --reporter-html report.html

GitHub Actions Integration

Here’s a real example from Bruno’s own CI pipeline:

Basic Setup

name: API Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    name: Run API Tests
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20'
      
      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli
      
      - name: Run API Tests
        run: |
          cd packages/bruno-tests/collection
          bru run --env Prod --output junit.xml --format junit
      
      - name: Publish Test Report
        uses: EnricoMi/publish-unit-test-result-action@v2
        if: always()
        with:
          check_name: API Test Results
          files: packages/bruno-tests/collection/junit.xml

GitLab CI Integration

.gitlab-ci.yml

stages:
  - test

api-tests:
  stage: test
  image: node:20
  
  before_script:
    - npm install -g @usebruno/cli
  
  script:
    - cd api-tests
    - bru run --env Production --output results.json
  
  artifacts:
    when: always
    reports:
      junit: api-tests/junit.xml
    paths:
      - api-tests/results.json

Jenkins Pipeline

Jenkinsfile

pipeline {
  agent any
  
  stages {
    stage('Install Bruno CLI') {
      steps {
        sh 'npm install -g @usebruno/cli'
      }
    }
    
    stage('Run API Tests') {
      steps {
        dir('api-tests') {
          sh 'bru run --env Production --output junit.xml --format junit'
        }
      }
    }
  }
  
  post {
    always {
      junit 'api-tests/junit.xml'
    }
  }
}

Advanced CLI Options

Environment Variables

Override individual environment variables:

bru run --env Production --env-var API_KEY=secret123

Override multiple variables:

bru run \
  --env Production \
  --env-var API_KEY=secret123 \
  --env-var BASE_URL=https://api.staging.example.com

SSL Certificates

Use custom CA certificates:

bru run --cacert myCustomCA.pem

Use only custom CA (ignore default truststore):

bru run --cacert myCustomCA.pem --ignore-truststore

Request Control

Bail on Failure

Stop execution after first failure:

bru run --bail

Add Delay

Add delay between requests (in milliseconds):

bru run --delay 1000

Skip Headers

Skip headers in reports:

bru run --reporter-skip-all-headers

Insecure Mode

Allow insecure server connections:

bru run --insecure

CSV Data-Driven Testing

Run collection with CSV data:

bru run --csv-file-path data.csv

Client Certificates

Provide client certificate configuration:

bru run --client-cert-config cert-config.json

Docker Integration

Run Bruno tests in a Docker container:

Dockerfile

FROM node:20-alpine

WORKDIR /tests

# Install Bruno CLI
RUN npm install -g @usebruno/cli

# Copy collection
COPY ./api-tests /tests

# Run tests
CMD ["bru", "run", "--env", "Production", "--output", "results.json"]

Use in CI:

steps:
  - name: Build test image
    run: docker build -t api-tests .
  
  - name: Run tests
    run: docker run api-tests

Best Practices

Store collections in version control

Keep your Bruno collections alongside your code in Git. This ensures tests stay in sync with your API changes.

Use environments for different stages

Create separate environment files for Development, Staging, and Production:

environments/
├── Development.bru
├── Staging.bru
└── Production.bru

Generate reports for visibility

Always generate test reports in CI to track failures and history:

bru run --reporter-junit junit.xml --reporter-html report.html

Use --bail for fast feedback

In CI pipelines, use --bail to fail fast and save build time:

bru run --bail --env Production

Keep secrets in CI variables

Never commit sensitive data. Use CI environment variables:

bru run --env Production --env-var API_KEY=$CI_API_KEY

Exit Codes Reference

Use these exit codes for scripting and CI failure detection:

Code	Meaning
0	Execution successful
1	Assertion, test, or request failed
2	Output directory doesn’t exist
3	Request chain loops endlessly
4	Not in collection root directory
5	Input file doesn’t exist
6	Environment doesn’t exist
7	Environment override not string or object
8	Environment override malformed
9	Invalid output format
255	Other error occurred

Troubleshooting

Error: Not in collection root directory

Make sure you’re running bru from the directory containing bruno.json. Use cd to navigate to your collection first.

Error: Environment doesn’t exist

Check that your environment file exists in the environments/ folder and the name matches exactly (case-sensitive).

Debugging CI failures

Add the --output results.json flag to capture detailed error information for debugging failed CI runs.