- On IronBee: IronBee verifies the change on its own infrastructure. Nothing is installed on your runner.
- On your GitLab runner: the verification runs inside your pipeline with your own Anthropic access.
gitlab.com/ironbee-ai/ironbee-gitlab/verify. This guide gets it running in a few minutes. For the mechanics behind it, see How it works.
Prerequisites
- An IronBee account and your account API key. Owners and admins find it in the console under Settings > Account. Other members can ask an owner or admin for it.
- To verify on IronBee: the project’s group connected to IronBee. A public project also works without it.
- To verify on your GitLab runner, or to have findings fixed: an Anthropic API key from console.anthropic.com, or a Claude Code OAuth token from
claude setup-token. - To post the report note and push fixes: a GitLab project access token. See The GitLab token.
- A project on gitlab.com. Self-managed GitLab and GitLab Dedicated aren’t supported.
Set it up from the console
The fastest path is the console, which writes the pipeline file for you.1
Connect GitLab
Open Settings > Getting started. On the GitLab card, click Add the Component, or Connect GitLab to connect your GitLab group first. See GitLab. On Projects, a GitLab project’s Install the IronBee Component opens the same steps for that project.
2
Answer three questions
In the IronBee Component step:
- Repository: the GitLab project the pipeline file and the variables go into.
- Where it runs: On IronBee (recommended) or On your GitLab runner.
- On a finding: Report it, or Fix it too.
3
Set it up on GitLab
Fill in how your app starts, then add the CI/CD variables the console lists: Open CI/CD variables opens the project’s settings, and Open access tokens is where you create the
GITLAB_TOKEN. Click Copy and open the pipeline editor: the console copies the file and opens GitLab’s pipeline editor. Paste it there and commit. If the project already has a .gitlab-ci.yml, add the include block to it instead; Copy the pipeline file copies the file again. The commit is a push, and that push starts your first verification.Add the component
Add the component to.gitlab-ci.yml with one of the two starters below.
- On IronBee, report only
- On your runner, fixing too
app_* lines with your own install, build and start commands and the port your app listens on. If your app is already deployed at a public preview URL, delete the four lines and set app_url instead. The component needs one of the two: without a target the run stops before it verifies anything. See Verifying your application.
Every input is a string. Quote numbers and true/false, as in app_port: '3000': GitLab refuses an input whose value isn’t a string. No credential appears in the file: the credential inputs read the CI/CD variables below by default.
To have findings fixed while verifying on IronBee, add an Anthropic credential, set verification_apply_fix: 'true' and raise the job’s timeout: to 150m, as the console does for Fix it too: a fixed app on the runner is verified a second time. Before that re-verification, the component runs app_build_command and app_start_command again. When the start command hands off to Docker Compose or a service, set app_restart_command; see Apps started through Docker Compose or a service. On your runner, verification_apply_fix: 'false' has the agent report what it finds and change no file. A run that fixes, in either mode, needs the GITLAB_TOKEN to push its fixes.
The workflow: block is optional. It keeps a project that runs both branch and merge request pipelines to one pipeline per push, so a push to a branch with an open merge request doesn’t start two pipelines. See Running in GitLab CI/CD.
@v1 follows the latest release, so your pipeline gets fixes without editing the file. The starter file the console writes uses @1, which follows the same releases.
Add the CI/CD variables
In your GitLab project, open Settings > CI/CD > Variables and add each variable. Mark each one Masked, and leave it unprotected: a protected variable reaches only protected branches, so a merge request pipeline from another branch wouldn’t see it.
The
ironbee_api_key, anthropic_api_key, claude_code_oauth_token and gitlab_token inputs default to these variables. Your Anthropic key or token stays in GitLab: the component uses it only on your runner, and IronBee never receives it.
The next merge request or push to the default branch starts a verification run.
The GitLab token
A job’s ownCI_JOB_TOKEN can’t post a merge request note, push a commit or open a merge request. The component does those with the token in the gitlab_token input, $GITLAB_TOKEN by default:
Keep the token in a masked variable. The component never prints it, and masking keeps it out of anything git or a tool prints on its own.
Without a token, the component still verifies:
- The report stays in the job log, with a warning.
- A run that produced fixes fails, because it has nothing to push them with. The fixes exist only on the runner.
Forks
A merge request from a fork is refused: a pipeline of a fork’s code must not run with your project’s credentials, and the fork’s own pipeline has none. The component detects it at the plan step and says so instead of failing on an empty key.Next steps
Platform and local verification
How the component decides where the verification runs.
Running in GitLab CI/CD
How the component behaves on each pipeline source and what it reports.
Verifying your application
An app on the runner, Docker-in-Docker, or a deployed URL.
Configuration
Every input and output, with defaults.