Manual CLI Setup

If you prefer not to use the official GitHub Action, install Bruno CLI yourself. This is the same pattern every team copied before the official action existed: checkout, setup Node, install @usebruno/cli, run bru.

Prerequisites

Git installed
A GitHub repository containing a Bruno workspace
Node.js (for installing the Bruno CLI)

Demo workspace

To follow along with the video, clone the Bruno Automation Demo Workspace and open it in Bruno.

Create the workflow

Create the workflow directory:

mkdir -p .github/workflows

Create .github/workflows/bruno-api-tests.yml:

name: Bruno API Tests

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

permissions:
  contents: read

jobs:
  bruno-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "24"

      - name: Install Bruno CLI
        run: npm install -g @usebruno/cli

      - name: Prepare report directory
        run: mkdir -p reports

      - name: Run Bruno demo collection
        working-directory: collections/bruno-automation-demo
        run: |
          bru run \
            --global-env ci \
            --workspace-path ../.. \
            --tags smoke,workflow,release-gate \
            --env-var platform_name="GitHub Actions" \
            --env-var build_id="${{ github.run_id }}" \
            --env-var commit_sha="${{ github.sha }}" \
            --reporter-html ../../reports/github-actions-report.html

      - name: Upload Bruno report
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@v6
        with:
          name: bruno-report
          path: reports/github-actions-report.html
          if-no-files-found: error

What this workflow does

Step	Purpose
Check out repository	Clones your repo so the runner has access to the workspace and collections.
Set up Node.js	Installs Node.js, which is required to run the Bruno CLI.
Install Bruno CLI	Installs `@usebruno/cli` globally via npm.
Prepare report directory	Creates a `reports/` folder for the HTML test report.
Run Bruno demo collection	Runs `bru run` from inside the collection directory.
Upload Bruno report	Saves the HTML report as a downloadable GitHub Actions artifact.

Key `bru run` flags

--global-env ci activates the ci global environment defined in environments/ci.yml at the workspace root.
--workspace-path ../.. tells Bruno where the workspace root is relative to the collection directory. Required when running from inside a collection folder.
--tags smoke,workflow,release-gate runs only requests tagged with these values.
--env-var overrides environment variables at runtime, useful for injecting CI-specific values like the GitHub run ID and commit SHA.
--reporter-html generates an HTML report of the test results.

For a full list of CLI options, see Command Options.

Run the workflow

Commit and push your workflow file:

git add .github/workflows/bruno-api-tests.yml
git commit -m "Add Bruno API test workflow"
git push origin main

Monitor the workflow:
- Go to your GitHub repository and click the Actions tab.
- The workflow runs automatically on pushes and pull requests to main, or trigger it manually with workflow_dispatch.
View the report:
- Once the run completes, click into the workflow run.
- Download the bruno-report artifact from the Artifacts section.
- Open github-actions-report.html in your browser for a visual summary of all test results.

Troubleshooting

Sandbox migration (Bruno CLI v3+)

Bruno CLI v3 changed the default sandbox to Safe Mode. If your tests rely on Node built-ins (require, Buffer, etc.), add --sandbox developer to your bru run command:

run: bru run --env ci --sandbox developer

exit-code is non-zero but failed is 0

The bru process crashed before writing JUnit, or wrote an empty report. Treat as a runtime error and check the step log for stderr. When using the official action, expand the ::group:: block in the action log to see the full bru invocation, including auto-injected flags.

Job failed before bru could run

If the run log shows a red Install Bruno CLI step, the failure is in npm install -g @usebruno/cli, not in your collection.

stderr substring	Likely cause	Fix
`E404` / `404 Not Found`	`bru-version` does not exist on npm	Pick a real version or use `latest`
`ENOTFOUND` / `ETIMEDOUT`	Runner cannot reach `registry.npmjs.org`	Check corporate proxy or network policy
`EACCES`	Self-hosted runner missing install permission	Adjust npm prefix or permissions
`ENOSPC`	Self-hosted runner disk full	Clear disk space
`EINTEGRITY`	Corrupted npm cache	Run `npm cache clean --force` and retry

Common bru exit codes

Code	Meaning
`0`	All requests, tests, and assertions passed
`1`	One or more requests, tests, or assertions failed
`4`	`bru` was invoked outside a collection root. Set `working-directory` to the collection dir
`6`	Environment file not found. Check `environments/<env>` exists
`12`	`--global-env` used without `--workspace-path`. Add `--workspace-path`
`137`	Process killed (usually OOM). Use a bigger runner or split the collection

See the action README for the full exit-code table.

Network timeouts and proxies

Bruno honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Set them via env: on the step or runner configuration.

Getting Started

Core Features

API Tools

Developer Tools

License Management

Advanced Guides

Prerequisites

Demo workspace

Create the workflow

What this workflow does

Key `bru run` flags

Run the workflow

Troubleshooting

​Prerequisites

​Demo workspace

​Create the workflow

​What this workflow does

​Key bru run flags

​Run the workflow

​Troubleshooting

Prerequisites

Demo workspace

Create the workflow

What this workflow does

Key `bru run` flags

Run the workflow

Troubleshooting