Bruno v3 → v4: Breaking Changes

Bruno v4 brings meaningful improvements to how secrets are stored, how environment variables behave, and what the collection schema supports. Most of the changes are automatic when you upgrade through the app. But a handful of them require attention before you upgrade, especially if your scripts touch sensitive values or your team runs mixed Bruno versions. This guide walks through every change, who is affected, and exactly what to do.

What Changed in v4 at a Glance

Secret Manager Config Moves into Environments

What is changing

In v4, external secrets configuration no longer lives in a secrets.json file at the root of your collection. It moves into your environment files, under a new externalSecrets section, managed from the Environment UI instead of from Collection Settings > Secrets.

Only the secret manager configuration moves. Your actual secret values are never written into the collection. Secret encryption and storage work the same way as before.

You also get a simpler way to reference a secret by its name directly:

Both forms resolve to the same value for now, so nothing breaks immediately. The old {{$secrets.*}} form is deprecated and support is removed after three months. Wherever the old syntax appears in your scripts and requests, the app marks it with an underline and a hover tooltip pointing you to the new form.

Why this change was made

Secrets are environment-specific. Your Production token is not your Staging token, so keeping the configuration alongside the environment it belongs to is clearer. It removes a separate root-level file to manage, makes the environment the single source of truth for secrets, and brings full secret-manager support to the CLI across AWS, Azure, and Vault. The old secrets.json model also could not support workspace and global environments — the new model can.

What you need to do

Before and after

Before — secrets.json at the collection root:

{
  "type": "aws-secrets-manager",
  "data": [
    {
      "environment": "Production",
      "secrets": [
        { "name": "dbPassword", "secretName": "prod/db/credentials", "enabled": true },
        { "name": "apiKey",     "secretName": "prod/payment/api-key",  "enabled": true }
      ]
    }
  ]
}

After — YAML format, environments/production.yml:

name: Production
variables:
  - name: baseUrl
    value: https://api.example.com
externalSecrets:
  type: aws-secrets-manager
  variables:
    - name: dbPassword
      secretName: prod/db/credentials
      enabled: true
    - name: apiKey
      secretName: prod/payment/api-key
      enabled: true

After — BRU (legacy) format, environments/staging.bru:

vars {
  baseUrl: https://staging.api.example.com
}
vars:externalsecrets:aws-secrets-manager {
  dbPassword: staging/db/credentials
  ~apiKey: staging/payment/api-key
}

Environment Variable Changes Are Saved to Disk by Default

What is changing

In v4, scripts that modify environment variables automatically persist those changes to disk. This makes script-driven variable updates consistent and predictable. The thing to watch out for is that if your scripts set tokens, credentials, or other sensitive values with bru.setEnvVar(), bru.deleteEnvVar(), or bru.setGlobalEnvVar(), those values will now be written to your environment file and could be committed to version control by accident.

How each API behaved before v4

Who is affected

How to prepare

Non-sensitive values do not need to change. If your script sets a baseUrl, a page counter, or a request ID, persisting it to disk is fine and you do not need to do anything.

Multiple WebSocket Messages

What is new

In v4 you can add multiple WebSocket messages to a single request. To support this, Bruno saves YAML WebSocket requests in a new message format. BRU (legacy) format collections are not affected by this schema change.

Nothing to migrate before upgrading. Your existing WebSocket requests keep working. The main thing to plan for is mixed-version teams.

Schema change (YAML format only)

message:
  type: json
  data: "{ \"action\": \"ping\" }"

message:
  - title: Ping message
    selected: true
    message:
      type: json
      data: |-
        { "action": "ping" }

If some teammates are on older versions and you save a WebSocket request with multiple messages in v4, they may not load that request correctly in v3.5.0 or earlier. The simplest fix is to coordinate the upgrade across the team.

Descriptions and Variable Types

What is new

In v4 you can add descriptions to params, headers, multipart form fields, and variables, and assign types to variables. Bruno stores these as annotations on the line above each pair: descriptions as @description('...'), and types as @string, @number, @boolean, or @object.

Nothing to migrate before upgrading. The mixed-version caveat below is the main thing to plan for.

How older versions handle the new schema

Schema change examples

headers {
  Content-Type: application/json
  Authorization: Bearer 
}
vars:pre-request {
  baseUrl: https://api.example.com
  retryCount: 3
}

headers {
  @description('Payload format')
  Content-Type: application/json
  @description('Auth token')
  Authorization: Bearer 
}
vars:pre-request {
  @string
  @description('Base URL for all requests')
  baseUrl: https://api.example.com
  @number
  retryCount: 3
}

runtime:
  variables:
    - name: baseUrl
      value: https://api.example.com
    - name: retryCount
      value: "3"

runtime:
  variables:
    - name: baseUrl
      value: https://api.example.com
      description: Base URL for all requests
    - name: retryCount
      value:
        type: number
        data: "3"

CLI JUnit Report: classname Now Uses the Request Path

What is changing

In the CLI JUnit reporter, each test case's classname attribute changes from the request URL to the collection path including the request name. For example, a request called Get Users inside a Users folder would produce Users/Get Users as the classname.

The reason for this change is that CI tools like Xray and Azure DevOps use classname + name as a test's unique identifier. Because the URL changes per environment, the same test produced a different classname when run against staging versus production, and it showed up as duplicate test cases. The collection path is stable across environments so the same test now maps to a single entry.

Before and after

<!-- Staging run -->
<testcase
  name="Status is 200"
  classname="https://staging.api.example.com/users"
/>

<!-- Production run -->
<testcase
  name="Status is 200"
  classname="https://prod.api.example.com/users"
/>

<!-- Staging run -->
<testcase
  name="Status is 200"
  classname="Users/Get Users"
/>

<!-- Production run -->
<testcase
  name="Status is 200"
  classname="Users/Get Users"
/>

What you need to do: If your CI tooling or scripts read classname expecting a URL, update them to expect the collection path format instead. If you only need the request name, extract it from the last segment of the path. You are not affected if you do not consume the CLI's JUnit output or do not key on classname.

Before You Upgrade Checklist

Work through this list before upgrading any machine in your team.

Once on v4

Audit your scripts, coordinate your team, and the upgrade to v4 is straightforward.