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

# Custom configuration in Bitbucket

> Override any IronBee CLI setting the Bitbucket Pipe doesn't expose as a dedicated variable, with IRONBEE_EXTRA_CONFIG.

Most behavior is controlled by the pipe's [dedicated variables](https://docs.ironbee.ai/bitbucket-pipe/configuration/configuration.md). For anything else, `IRONBEE_EXTRA_CONFIG` passes raw JSON that is deep-merged into the `.ironbee/config.json` the pipe generates. Your keys win over the defaults.

> [!NOTE]
>
> `IRONBEE_EXTRA_CONFIG` applies to local mode only, when the verification runs inside the pipe. On IronBee, the pipe logs a warning and ignores it.

***

## How it works

Pass a JSON object as a string. It's merged on top of the configuration the pipe generates, so you only list the keys you want to change:

```yaml theme={null}
- pipe: docker://ghcr.io/ironbee-ai/ironbee-bitbucket:v1
  variables:
    IRONBEE_API_KEY: $IRONBEE_API_KEY
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
    VERIFICATION_MODE: "local"
    IRONBEE_EXTRA_CONFIG: '{"maxRetries": 5}'
```

Any key from the IronBee CLI configuration is accepted. See the [CLI configuration reference](https://docs.ironbee.ai/cli/configuration/configuration.md) for the full set.

During the run, the pipe writes its own `.ironbee/config.json`, so a configuration file committed to your repository isn't used. With `IRONBEE_EXCLUDE_FILES` on, the default, the pipe restores your file when the run ends.

***

## Tuning the DevTools server

The [local-mode platforms](https://docs.ironbee.ai/bitbucket-pipe/guides/verification-platforms.md) are served by one `ironbee-devtools` MCP server. Pass extra environment variables to it under `ironbeeDevTools.env`:

```yaml theme={null}
    IRONBEE_EXTRA_CONFIG: '{"ironbeeDevTools": {"env": {"BROWSER_HEADLESS_ENABLE": "true"}}}'
```

See the CLI's [DevTools MCP overrides](https://docs.ironbee.ai/cli/configuration/configuration.md#devtools-mcp-overrides) for the keys the server accepts.

> [!NOTE]
>
> IronBee always sets its own invariants (the tool-name prefix, metadata flags and platform) last. They can't be overridden through `IRONBEE_EXTRA_CONFIG`.

***

## Committing the generated setup

The changes IronBee's setup makes to `.claude/`, `.mcp.json` and `.gitignore` stay out of the commits the pipe makes, because they're its working files rather than the change being verified. To commit the setup it generated together with a fix, for example to use it for local development, set `IRONBEE_EXCLUDE_FILES: "false"`. A run that commits no fix commits no setup either. `.ironbee/` stays out either way.

***

## What's next?

> [card] [Local-mode platforms](https://docs.ironbee.ai/bitbucket-pipe/guides/verification-platforms.md)
>
> The platforms the DevTools server provides.

> [card] [Configuration](https://docs.ironbee.ai/bitbucket-pipe/configuration/configuration.md)
>
> Every variable and output, with defaults.


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