Skip to main content
Every run needs a target: the running application the verification exercises. You give the action one of two:
  • 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.
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 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.
On your runner, the agent runs these commands itself as part of the verification.

​
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 and runs app_start_command again. That’s right only when the 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.
  • app_logs_command prints the app’s own logs into the evidence artifact. Without it, the artifact holds only the output of the command that started the app.

​
A deployed URL

Point app_url at a public address:
The install, build and start commands aren’t used. Before the verification starts, the action requests the URL once:
  • A 401 or 403 answer fails the run, because the verification would only see a login page.
  • An unreachable URL 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 workflow runs again.

​
Protected deployments

A preview behind deployment protection or SSO needs a way in:
  • 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 GitHub secret. 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.
  • Verify 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.
An SSO redirect that answers 200 with a login page can’t be told apart from your app by its status code. In that case, 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, deployment and deployment_status events fall back to the deployment’s environment. Other events use 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.
If you pin ironbee_cli_version, use 0.44.0 or later for ironbee_environment.

​
Monorepos

Point the action 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. 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.