Skip to main content
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:
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.
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:
  • 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:
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:
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.
  • A project secret. Store the bypass in the IronBee project instead, so every run uses it. For Vercel, see 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.
  • 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:
  • 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:

Focusing the verification

The verification decides what to check from the changeset. Add instructions when you want specific coverage:
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?

Running in GitLab CI/CD

Pipeline sources, fixes and the report.

Configuration

Every input and output, with defaults.