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

# Verifying your application in GitLab

> Choose what the GitLab component verifies, an app it starts on the runner, a Docker-in-Docker service or a deployed URL, and how to reach it.

Every run needs a target: the running application the verification exercises. You give the component one of two:

* **An app on the runner.** The component starts your app during the job. IronBee reaches it through a reverse tunnel.
* **A deployed URL.** Your app is already running at a public address, such as a review app or a preview deployment.

Without a target, the run stops at the plan step, before verifying anything.

***

## An app on the runner

Describe how your app is installed, built and started, and the port it listens on:

| Input | Purpose | Example |
| - | - | - |
| `app_install_command` | Install dependencies | `npm ci` |
| `app_build_command` | Build the app | `npm run build` |
| `app_start_command` | Start the app and keep it running | `npm run start` |
| `app_port` | The port the app listens on | `'3000'` |

```yaml theme={null}
include:
  - component: gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1
    inputs:
      app_install_command: npm ci
      app_build_command: npm run build
      app_start_command: npm run start
      app_port: '3000'
```

`app_port` is required with `app_start_command`. Instead of `app_port`, you can set a localhost URL with a port, such as `app_url: http://localhost:3000`. When both name a port, the one in `app_url` wins.

**On IronBee**, the component runs the commands itself and waits for the port to accept connections, 60 seconds by default (`app_wait_seconds`). IronBee then verifies the app through a reverse tunnel, and the app's output is saved as `app.log` in the job's [artifacts](https://docs.ironbee.ai/gitlab-component/advanced/evidence.md).

> [!NOTE]
>
> The tunnel carries plain HTTP. Serve the app over HTTP on that port; a port that answers with TLS fails the run immediately.

**On your runner**, the agent runs these commands itself as part of the verification. It's told the commands, the port and `app_url`.

The five commands reach bash as you wrote them: GitLab doesn't expand them, and bash expands them when they run. So `npm start -- --port ${PORT:-3000}` keeps its default.

### Which URLs count as on the runner

An `app_url` whose host IronBee can't reach from outside is treated as an app on the runner. On IronBee, it's reached through the tunnel. These hosts count:

* `localhost`, and any name ending in `.localhost`
* a loopback or private IPv4 address: `127.x`, `0.x`, `10.x`, `172.16.x` to `172.31.x`, `192.168.x`, and link-local `169.254.x`
* an IPv6 loopback (`::1`), unspecified (`::`), link-local (`fe80::/10`) or unique local (`fc00::/7`) address
* a name without a dot, such as `docker`, a service container or a Docker Compose service

Any other host is verified as a deployed URL. On IronBee, a URL on the runner still needs `app_start_command`: the component starts the app itself before the tunnel opens. The tunnel connects to the port on the runner's own loopback address. When `app_url` names another host, such as `http://docker:4000`, the component bridges `127.0.0.1:4000` to that host once the app answers there.

### Apps started through Docker Compose or a service

When the verification runs on IronBee and a fix is made, the component restarts the app so the re-verification sees the fixed code. By default it stops the process it started, together with the processes that one started, runs `app_build_command` again when it's set, and then `app_start_command`. The install command doesn't run again. That's right only when the start command runs the app itself.

When the command hands off to Docker Compose, a process manager or a service, set two more inputs:

```yaml theme={null}
      app_start_command: docker compose up -d
      app_restart_command: docker compose up -d --build
      app_logs_command: docker compose logs --no-color --tail=2000
      app_port: '3000'
```

* `app_restart_command` restarts the app with the fix. Without it, the re-verification would test the code from before the fix. The component first stops the process it started, if that one is still running, then runs the command to the end before the re-verification starts. So use a command that replaces the running app and returns, such as `docker compose up -d --build`; one that stays in the foreground holds the job.
* `app_logs_command` prints the app's own logs into the job's artifacts, as `app-service-logs.txt`. Without it, the artifacts hold only the output of the command that started the app.

### Docker-in-Docker

On GitLab's shared runners, an app started with Docker Compose runs on a `docker:dind` service and publishes its ports on that service, not on the job's loopback. On IronBee, point `app_url` at the service's host, and the component bridges the port to `127.0.0.1`, where the tunnel looks for it:

```yaml theme={null}
include:
  - component: gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1
    inputs:
      verification_mode: platform
      app_start_command: 'docker compose up -d --build'
      app_restart_command: 'docker compose up -d --build'
      app_logs_command: 'docker compose logs --no-color --tail=2000'
      app_url: 'http://docker:4000'
      app_wait_seconds: '300'

ironbee-verify:
  timeout: 150m
  services:
    - docker:27-dind
  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: /certs
    DOCKER_TLS_VERIFY: '1'
    DOCKER_CERT_PATH: /certs/client
  # The job's image is node:22-bookworm, which has no docker CLI. The CLI,
  # Compose v2 and Buildx come from Docker's own package repository.
  before_script:
    - apt-get update -qq && apt-get install -y -qq ca-certificates curl >/dev/null
    - install -m 0755 -d /etc/apt/keyrings
    - curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
    - 'echo "deb [signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list'
    - apt-get update -qq && apt-get install -y -qq docker-ce-cli docker-buildx-plugin docker-compose-plugin >/dev/null
```

Debian's own packages carry only Compose v1, the `docker-compose` command, so the example installs Docker's packages for `docker compose`. `app_wait_seconds` is how long both the bridge and the CLI wait for the app to answer. The plan logs the `timeout:` the job needs; with fixing on, an app on the runner can be verified twice.

***

## A deployed URL

Point `app_url` at a public address:

```yaml theme={null}
include:
  - component: gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1
    inputs:
      app_url: https://preview.example.com
```

The install, build and start commands aren't used. Before the verification starts, the component requests the URL once. On IronBee, the request carries `app_headers` and `app_secret_headers`, as the verification does; on your runner, it carries none. It doesn't follow a redirect:

* A `401` or `403` answer fails the run, because the verification would only see a login page.
* A redirect logs a warning naming where it leads. The verification follows it and reports on the page it lands on.
* A URL that doesn't answer from the runner logs a warning, because IronBee may reach addresses your runner can't.

A deployed URL isn't re-verified after a fix: the deployment still serves the code that was deployed. The loop closes when the fix is deployed and the pipeline runs again.

### Protected deployments

A preview behind deployment protection or SSO answers `401` or `403`, and the reachability request before the run fails on it. On IronBee, the ways past it are:

* **A secret header.** If the protection can be bypassed with a header, pass it in `app_secret_headers`, one `Name: value` per line, from a masked CI/CD variable. The reachability request sends it too, so the run gets past that check. IronBee encrypts the value and never returns it.

  ```yaml theme={null}
      app_url: https://preview.example.com
      app_secret_headers: "x-vercel-protection-bypass: $VERCEL_BYPASS_SECRET"
  ```

* **A project secret.** Store the bypass in the IronBee project instead, so every run uses it. For Vercel, see [Preview access](https://docs.ironbee.ai/integrations/vercel.md#preview-access). The component doesn't know the project's secrets, so its reachability request goes without the bypass: a project secret works for a preview that answers that request with a redirect or `200`, not with `401` or `403`.

* **The app on the runner.** Leave `app_url` empty and set `app_start_command` and `app_port`. This verifies the app, not the deployment, so edge configuration, rewrites and the deployed build aren't exercised.

On your runner, the headers aren't used, so a preview that answers `401` or `403` is refused whatever they hold. Verify the app on the runner instead.

A sign-in redirect is logged, not refused, and a login page served with `200` can't be told apart from your app by its status code. In both cases, the verdict describes the login page.

For headers that aren't secret, such as `x-e2e: 1`, use `app_headers`. Their values are stored as plain text.

***

## Environments

On IronBee, `ironbee_environment` names the project environment the run is against, such as `staging` or `preview`. The run uses that environment's variables and secrets on top of the project-wide ones.

```yaml theme={null}
      ironbee_environment: staging
```

* A name the project hasn't seen yet is created by the first run that uses it.

* When the input is empty, the run uses the job's own `environment:` (`CI_ENVIRONMENT_NAME`). Redeclare the job with `action: verify`, so each run isn't recorded as a deployment:

  ```yaml theme={null}
  ironbee-verify:
    environment: { name: staging, action: verify }
  ```

* With neither, the run uses the project-wide variables and secrets only.

* When the environment has **Domain** properties, `app_url` must be inside those domains. Runs on the runner are refused for that environment, because a tunnel has no domain.

***

## Monorepos

Point the component at a subdirectory with `working_directory`. The commands, the configuration and the verification run relative to it:

```yaml theme={null}
include:
  - component: gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1
    inputs:
      working_directory: packages/web-app
      app_install_command: npm ci
      app_start_command: npm run dev
      app_port: '5173'
```

***

## Focusing the verification

The verification decides what to check from the changeset. Add instructions when you want specific coverage:

```yaml theme={null}
      verification_prompt: 'Focus on the checkout flow and payment form validation'
```

`verification_prompt` reaches the verification in both modes. A literal `$` in it is written `$$`, because GitLab expands variables in every input except the five commands and `claude_code_args`. When the verification runs on your runner, you can also set `claude_code_max_turns` (default `'100'`) and `claude_code_model`.

***

## What's next?

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

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


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