- An app on the runner. The action starts your app during the workflow. IronBee reaches it through a reverse tunnel.
- A deployed URL. Your app is already running at a public address, such as a preview deployment.
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 action 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 to the ironbee-application-log artifact.
The tunnel carries plain HTTP. Serve the app over HTTP on that port; a port that answers with TLS fails the run immediately.
app_url.
Which URLs count as on the runner
Anapp_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.xto172.31.x,192.168.x, and link-local169.254.x - an IPv6 loopback (
::1), unspecified (::), link-local (fe80::/10) or unique local (fc00::/7) address - a name without a dot, such as a container name or a Docker Compose service
app_start_command: the action starts the app itself before the tunnel opens. The tunnel connects to the port on the runner’s own loopback address, whatever host the URL names. So for http://web:3000, the app has to accept connections on localhost:3000 on the runner, for example a container that publishes port 3000.
Apps started through Docker Compose or a service
When the verification runs on IronBee and a fix is made, the action 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, runsapp_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_commandrestarts the app with the fix. Without it, the re-verification would test the code from before the fix. It runs to the end before the re-verification starts, and the action doesn’t stop the app it started first, so use a command that replaces the running app and returns, such asdocker compose up -d --build.app_logs_commandprints the app’s own logs into theironbee-application-logartifact. Without it, the artifact holds only the output of the command that started the app.
A deployed URL
Pointapp_url at a public address:
app_headers and app_secret_headers, as the verification does; on your runner, it carries none. It doesn’t follow a redirect:
- A
401or403answer 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.
- An unreachable URL logs a warning, because IronBee may reach addresses your runner can’t.
Protected deployments
A preview behind deployment protection or SSO answers401 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, oneName: valueper line, from a GitHub secret. 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 action 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 with401or403. -
The app on the runner. Leave
app_urlempty and setapp_start_commandandapp_port. This verifies the app, not the deployment, so edge configuration, rewrites and the deployed build aren’t exercised.
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,
deploymentanddeployment_statusevents fall back to the deployment’s environment. Other events use the project-wide variables and secrets only. See Deployments for adeployment_statusworkflow. - When the environment has Domain properties,
app_urlmust be inside those domains. Runs on the runner are refused for that environment, because a tunnel has no domain.
ironbee_cli_version, use 0.44.0 or later for ironbee_environment.
Monorepos
Point the action at a subdirectory withworking_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 comment command with an instruction replaces it for that run. 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 CI
Triggers, fixes and the report.
Configuration
Every input and output, with defaults.