> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebruno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions Integration

[GitHub Actions](https://docs.github.com/en/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.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/UBAOzICJADs" title="GitHub Actions Integration with Bruno" allowFullScreen />

<Note>
  To follow along with the video, clone the [Bruno Automation Demo Workspace](https://github.com/bruno-collections/bruno-automation-demo-workspace) and open it in Bruno.
</Note>

## Prerequisites

* [Git](https://git-scm.com/downloads) installed.
* A GitHub repository containing a Bruno workspace.
* [Node.js](https://nodejs.org/) (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](/variables/global-environment-variables) 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:

```bash theme={null}
mkdir -p .github/workflows
```

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

```yaml theme={null}
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](/variables/global-environment-variables) 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](/bru-cli/commandOptions).

## Run the Workflow

1. **Commit and push** your workflow file:

```bash theme={null}
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](/bru-cli/overview)
* [Command Options](/bru-cli/commandOptions)
* [Generating Reports](/bru-cli/builtInReporters)
* [Global Environment Variables](/variables/global-environment-variables)
* [GitHub Actions Documentation](https://docs.github.com/en/actions)