Skip to main content
The IronBee GitLab component verifies every merge request and every push to the default branch against your running application and reports the result on the merge request. It’s the GitLab counterpart of the IronBee GitHub Action, with the same inputs, decisions and report. It can run the verification in one of two places:
  • 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.
When the verification finds a problem, the component can report it, or also write the fix and commit it. The component is published in the GitLab CI/CD Catalog as 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.
The console listens for the first pipeline and moves on when it arrives. The rest of this page builds the same file by hand.

Add the component

Add the component to .gitlab-ci.yml with one of the two starters below.
Replace the four 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.
At the start of every run, the component logs the timeout: its configuration needs. Set at least that much on the job: GitLab’s default job timeout is one hour, which may be less than your configuration needs. When GitLab stops a job mid-run, the verification is cancelled with it.
@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 own CI_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.
A run on IronBee that only reports needs no token. When IronBee publishes the run on the merge request itself, the component posts no note at all. See The report.

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.