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

# How the GitLab component works

> What happens in a run of the IronBee GitLab component, on IronBee or on your runner, from the plan to the report.

Every run of the IronBee GitLab component follows the same path:

1. It resolves a plan and verifies the change.
2. When fixing is on, it fixes what failed and commits the fix.
3. It reports on the merge request and passes or fails the job.

Only the verification step differs between the two [modes](https://docs.ironbee.ai/gitlab-component/concepts/verification-modes.md): on IronBee (platform mode) or on your GitLab runner (local mode). The component runs the same steps as the [GitHub Action](https://docs.ironbee.ai/github-action/concepts/how-it-works.md), in the same order.

***

## The run, step by step

```mermaid actions={false} theme={null}
flowchart TD
    A[Merge request, push, schedule or manual pipeline] --> B[Resolve the plan: mode, target, changeset]
    B -->|platform| C[Start a verification run on IronBee and follow it]
    B -->|local| D[Run Claude Code with IronBee DevTools on the runner]
    C --> E{Verdict}
    D --> E
    E -->|fail, fixing on| F[Fix, then re-verify where it can]
    F --> G[Commit to the MR branch or open a fix MR]
    E --> H[Report on the merge request and in the job log]
    G --> H
    H --> I[Pass or fail the job]
```

**1. Plan**

The component decides the mode, the target and the changeset, and logs them together with the reason for the mode and the minimum `timeout:` the job needs. It stops here, before installing anything, when the run can't work: no target, a merge request from a fork, or an invalid input value.

**2. Verify**

**On IronBee:** the component installs the IronBee CLI and runs `ironbee verify run web`. That starts a verification run on IronBee and follows it until it ends.

* For an app that runs on the runner, the component installs, builds and starts it first, and IronBee reaches it through a reverse tunnel.
* The recording, screenshots and logs are kept in the IronBee Console.

**On your runner:** the component installs Chromium, IronBee DevTools and Claude Code, writes `.ironbee/config.json` and runs `ironbee install --client claude`. Claude Code then verifies the change through IronBee DevTools. The evidence goes to the job's artifacts and to IronBee.

**3. Fix**

This step runs when the verification fails, fixing is on (`verification_apply_fix`) and an Anthropic credential is set.

* **On IronBee:** a Claude Code run on your runner edits the files to fix the reported issues. For an app that runs on the runner, the component then restarts it and runs a second verification. A deployed URL isn't re-verified, because the deployment still serves the code that was deployed.
* **On your runner:** the agent fixes and re-verifies in the same session. With fixing off, it reports what it finds and changes no file.

**4. Commit**

The component commits and pushes the fix itself, with the [GitLab token](https://docs.ironbee.ai/gitlab-component/get-started/getting-started.md#the-gitlab-token); the agent only edits files. Only the files the fix changed are committed.

* On a merge request, the fix goes to the merge request's source branch.
* Otherwise it goes to a new `ironbee/fix-<sha7>-<pipeline_id>` branch with a merge request.
* A fix whose re-verification fails is not pushed.

Fix commits end in `[skip ci]` and are pushed with `-o ci.skip`, so a fix doesn't start a pipeline that verifies it again.

**5. Report**

The report is posted as a merge request note, updated in place on later runs. It links to the run in the IronBee Console. When IronBee publishes the run on the merge request itself, the component posts no note. GitLab has no job summary, so the report is also printed in a collapsed **IronBee Verification Report** section of the job log and saved as `report.md` in the job's artifacts.

**6. Pass or fail**

The last step fails the job when the verification fails or ends without a verdict.

***

## What gets verified

The component binds each run to the change behind the pipeline, so the verification looks at what changed rather than at the whole repository.

| Pipeline source | What gets verified |
| - | - |
| `merge_request_event` | The whole merge request |
| `push` | Every commit in the push, from the push's `before` commit (`CI_COMMIT_BEFORE_SHA`), or the commit against its parent when that base isn't usable |
| `schedule`, `web`, `api`, `trigger` | On IronBee: the commit against its parent. On your runner: the whole application |

To verify the application without the repository, for example a private project whose group isn't connected to IronBee, set `ironbee_bind_repository: 'false'`.

***

## Where results appear

* **On the merge request:** the component's report note, with a link to the run in the console. When the project's [GitLab group is connected](https://docs.ironbee.ai/integrations/gitlab.md), IronBee publishes a run on IronBee itself instead: a pipeline status on the verified commit and, on a merge request, inline comments and a summary note. The component then leaves its note out.
* **In the pipeline:** the report in the job log, the job's pass or fail result, and the job's artifacts. The `IRONBEE_VERDICT`, `IRONBEE_MODE`, `IRONBEE_JOB_ID`, `IRONBEE_JOB_URL`, `IRONBEE_ARTIFACTS_URL` and `IRONBEE_PLATFORM_PUBLISHES` [outputs](https://docs.ironbee.ai/gitlab-component/configuration/configuration.md#outputs) are available to later jobs.
* **In the IronBee Console:** runs on IronBee appear on the project's **Verifications** tab with the trigger **GitLab CI**. The project is the GitLab project unless you set `ironbee_project`. See [Verifications](https://docs.ironbee.ai/console/verifications.md).

***

## What's next?

> [card] [Platform and local verification](https://docs.ironbee.ai/gitlab-component/concepts/verification-modes.md)
>
> Choose where the verification runs.

> [card] [Running in GitLab CI/CD](https://docs.ironbee.ai/gitlab-component/guides/running-in-ci.md)
>
> Pipeline sources, fix behavior and the report.


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