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
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 ciactivates theciglobal environment defined inenvironments/ci.ymlat 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-gateruns only requests tagged with these values.--env-varoverrides environment variables at runtime, useful for injecting CI-specific values like the GitHub run ID and commit SHA.--reporter-htmlgenerates an HTML report of the test results.
For a full list of CLI options, see bru run 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.htmlin your browser for a visual summary of all test results.
Troubleshooting
bru run jobs can retain memory per request and exhaust a small CI VM. If the runner dies mid-collection, add --experimental-cache-modules:
run: bru run --env ci --experimental-cache-modules
Do not enable the flag unless you see this RSS growth. See Reduce CLI memory use on large runs.
require, Buffer, etc.), add --sandbox developer to your bru run command:
run: bru run --env ci --sandbox developer
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.
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 |
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.
HTTP_PROXY, HTTPS_PROXY, and NO_PROXY. Set them via env: on the step or runner configuration.