GitHub Actions Integration

GitHub Actions is a powerful continuous integration and continuous delivery (CI/CD) platform that enables you to automate your software development workflows directly from your GitHub repository. It provides seamless integration with GitHub’s ecosystem, making it an ideal choice for teams looking to automate their API testing workflows.

Bruno CLI integrates seamlessly with GitHub Actions to automate API testing workflows.

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

Prerequisites

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

Workspace Structure

The demo workspace is organized as a Bruno workspace with an OpenCollection layout:

bruno-automation-demo-workspace/
├── .github/
│   └── workflows/
│       └── bruno-api-tests.yml
├── collections/
│   └── bruno-automation-demo/
│       ├── 01-smoke-checks/
│       ├── 02-ci-workflow/
│       ├── 03-release-gates/
│       ├── environments/
│       │   ├── ci.bru
│       │   ├── local.bru
│       │   └── staging.bru
│       └── opencollection.yml
├── environments/
│   ├── ci.yml
│   ├── local.yml
│   └── staging.yml
├── workspace.yml
└── reports/

Key items:

• workspace.yml — defines the workspace and points to the collection at collections/bruno-automation-demo.
• environments/ci.yml — a global environment with variables like bruno_echo_url, platform_name, and build_id used across all collections.
• collections/bruno-automation-demo/ — the collection itself, containing folders of requests with tests and assertions.

Create the GitHub Actions Workflow

1. In your repository, create the workflow directory:

mkdir -p .github/workflows

2. 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 (see details below).
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. This is required when running bru run from inside a collection folder.
• --tags smoke,workflow,release-gate — only runs 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

1. 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

2. 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 you can trigger it manually with workflow_dispatch.

3. 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.

Learn More

• Bruno CLI Overview
• Command Options
• Generating Reports
• Global Environment Variables
• GitHub Actions Documentation