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

> ## Agent Instructions
> IronBee (ironbee.ai) is an AI QA engineer: it verifies code changes against the running app and keeps the evidence. It is not related to the IronBee open-source web application firewall.
> The console is at https://console.ironbee.ai.
> Install the CLI with `npm install -g @ironbee-ai/cli`, sign in with `ironbee login`, and set up a project with `ironbee install`.
> In GitHub workflows, use the action as `ironbee-ai/ironbee-action@v1` and pass the `IRONBEE_API_KEY` secret as the `ironbee_api_key` input.
> In GitLab pipelines, include the component `gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1`; it reads the `IRONBEE_API_KEY` CI/CD variable by default.
> In Bitbucket Pipelines, run the pipe `docker://ghcr.io/ironbee-ai/ironbee-bitbucket:v1` and pass `IRONBEE_API_KEY: $IRONBEE_API_KEY` and `BITBUCKET_OAUTH_TOKEN: $BITBUCKET_OAUTH_TOKEN` under its `variables:`.
> Console scenarios (https://docs.ironbee.ai/console/scenarios) and CLI saved scenarios (https://docs.ironbee.ai/cli/guides/scenarios) are separate features.
> For plans and prices, link to https://ironbee.ai/pricing; the website is the source of truth for them.

# Get started with the GitHub Action

> Add IronBee verification to your GitHub Actions workflow.

The IronBee GitHub Action verifies every push and pull request against your running application and reports the result on the pull request. It can run the verification in one of two places:

* **On IronBee**: IronBee verifies the change on its own infrastructure. Nothing is installed on your runner.
* **On your GitHub runner**: the verification runs inside your workflow with your own Anthropic access.

When the verification finds a problem, the action can report it, or also write the fix and commit it.

This guide gets the action running in a few minutes. For the mechanics behind it, see [How it works](https://docs.ironbee.ai/github-action/concepts/how-it-works.md).

***

## Prerequisites

* An [IronBee account](https://console.ironbee.ai) and your account API key. Owners and admins find it in the console under **Settings > Account**. Other members can ask an owner or admin for it.
* To verify **on IronBee**: the [IronBee GitHub App](https://docs.ironbee.ai/integrations/github.md) installed on the repository. A public repository also works without it.
* To verify **on your GitHub runner**, or to have findings fixed: an Anthropic API key from [console.anthropic.com](https://console.anthropic.com), or a Claude Code OAuth token from `claude setup-token`.

***

## Set it up from the console

The fastest path is the console, which writes the workflow for you.

**1. Connect GitHub**

Open **Settings > Getting started**. On the **GitHub** card, click **Add the Action**, or **Connect GitHub** to install the IronBee GitHub App first. On **Projects**, a GitHub project's **Install the IronBee Action** opens the same steps for that repository.

**2. Answer three questions**

In the **IronBee Action** step:

* **Repository**: the repository the workflow file and the secrets go into.
* **Where it runs**: **On IronBee** (recommended) or **On your GitHub runner**.
* **On a finding**: **Report it**, or **Fix it too**.

![The IronBee Action step: the repository acme / web picked, Where it runs open with On IronBee (recommended) selected and On your GitHub runner, and On a finding set to Report it](https://mintcdn.com/ironbee/Ga5ZIxAT3IUrLTxO/images/console/integrations/onboarding-github-action-light.png?fit=max\&auto=format\&n=Ga5ZIxAT3IUrLTxO\&q=85\&s=1e114b5570775f1c1d11f159b8ec8106)

![The IronBee Action step: the repository acme / web picked, Where it runs open with On IronBee (recommended) selected and On your GitHub runner, and On a finding set to Report it](https://mintcdn.com/ironbee/Ga5ZIxAT3IUrLTxO/images/console/integrations/onboarding-github-action-dark.png?fit=max\&auto=format\&n=Ga5ZIxAT3IUrLTxO\&q=85\&s=542eb3e69e5d66d262107757f8be68e2)

**3. Set it up on GitHub**

Fill in how your app starts, add the repository secrets the console lists, then click **Create the file on GitHub**. Committing the file is a push, and that push starts your first verification.

The rest of this page builds the same workflow by hand.

***

## Add the workflow

Create `.github/workflows/ironbee.yml` with one of the two starter workflows below. The action is also listed on the [GitHub Marketplace](https://github.com/marketplace/actions/ironbee-action).

> [tab] On IronBee, report only
>
> ```yaml theme={null}
> name: IronBee Verification
>
> on:
>   push:
>     branches: [main]
>   pull_request:
>     types: [opened, synchronize]
>
> permissions:
>   contents: write
>   pull-requests: write
>   issues: write
>
> concurrency:
>   group: ironbee-${{ github.event.pull_request.number || github.ref }}
>   cancel-in-progress: true
>
> jobs:
>   verify:
>     runs-on: ubuntu-latest
>     timeout-minutes: 90
>     steps:
>       - uses: actions/checkout@v4
>       - uses: ironbee-ai/ironbee-action@v1
>         with:
>           ironbee_api_key: ${{ secrets.IRONBEE_API_KEY }}
>           verification_mode: platform
>           verification_apply_fix: false
>           # Where the app runs during the workflow: on this runner ...
>           app_install_command: npm ci
>           app_build_command: npm run build
>           app_start_command: npm run start
>           app_port: 3000
>           # ... or at a preview URL instead of the four lines above:
>           # app_url: https://preview.example.com
> ```

> [tab] On your runner, fixing too
>
> ```yaml theme={null}
> name: IronBee Verification
>
> on:
>   push:
>     branches: [main]
>   pull_request:
>     types: [opened, synchronize]
>
> permissions:
>   contents: write
>   pull-requests: write
>   issues: write
>
> concurrency:
>   group: ironbee-${{ github.event.pull_request.number || github.ref }}
>   cancel-in-progress: true
>
> jobs:
>   verify:
>     runs-on: ubuntu-latest
>     timeout-minutes: 90
>     steps:
>       - uses: actions/checkout@v4
>       - uses: ironbee-ai/ironbee-action@v1
>         with:
>           ironbee_api_key: ${{ secrets.IRONBEE_API_KEY }}
>           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
>           verification_mode: local
>           verification_apply_fix: true
>           # Where the app runs during the workflow: on this runner ...
>           app_install_command: npm ci
>           app_build_command: npm run build
>           app_start_command: npm run start
>           app_url: http://localhost:3000
>           # ... or at a preview URL instead of the four lines above:
>           # app_url: https://preview.example.com
> ```

Replace the four `app_*` lines with your own install, build and start commands and the port your app listens on. If your app is already deployed at a public preview URL, delete the four lines and set `app_url` instead. The action needs one of the two: without a target the run stops before it verifies anything. See [Verifying your application](https://docs.ironbee.ai/github-action/guides/verifying-your-app.md).

To have findings fixed while verifying on IronBee, add an Anthropic credential, set `verification_apply_fix: true` and raise `timeout-minutes` to `150`, as the console does for **Fix it too**: a fixed app on the runner is verified a second time. Before that re-verification, the action runs `app_build_command` and `app_start_command` again. When the start command hands off to Docker Compose or a service, set `app_restart_command`; see [Apps started through Docker Compose or a service](https://docs.ironbee.ai/github-action/guides/verifying-your-app.md#apps-started-through-docker-compose-or-a-service). On your runner, `verification_apply_fix: false` has the agent report what it finds and change no file.

> [!TIP]
>
> At the start of every run, the action logs the `timeout-minutes` its configuration needs. If that is more than your job allows, raise `timeout-minutes`. When GitHub stops a job mid-run, the verification is cancelled with it.

***

## Add the secrets

In your repository, open **Settings > Secrets and variables > Actions** and click **New repository secret** for each one:

| Secret | Value | Needed for |
| - | - | - |
| `IRONBEE_API_KEY` | Your IronBee account API key | Every run |
| `ANTHROPIC_API_KEY` | An Anthropic API key | Verifying on your runner, or fixing |
| `CLAUDE_CODE_OAUTH_TOKEN` | A Claude Code OAuth token, instead of `ANTHROPIC_API_KEY` | Verifying on your runner, or fixing |

Pass the Claude Code token with `claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}` instead of `anthropic_api_key`. Your Anthropic key or token stays in GitHub: the action uses it only on your runner, and IronBee never receives it.

The next push or pull request starts a verification run.

***

## Required permissions

The action needs these GitHub token permissions:

| Permission | Purpose |
| - | - |
| `contents: write` | Commit fixes to the pull request branch and create fix branches |
| `pull-requests: write` | Post the verification report and open fix pull requests |
| `issues: write` | Update the report comment, and react to comment commands |

A pull request from a fork receives no secrets, so no verification can run there. The action detects it and says so instead of failing on an empty key.

***

## Next steps

> [card] [Platform and local verification](https://docs.ironbee.ai/github-action/concepts/verification-modes.md)
>
> How the action decides where the verification runs.

> [card] [Running in CI](https://docs.ironbee.ai/github-action/guides/running-in-ci.md)
>
> How the action behaves on each trigger and what it reports.

> [card] [Verify from a comment](https://docs.ironbee.ai/github-action/guides/comment-trigger.md)
>
> Start a verification with `/ironbee-verify` on a pull request.

> [card] [Configuration](https://docs.ironbee.ai/github-action/configuration/configuration.md)
>
> Every input and output, with defaults.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.