CI_PIPELINE_SOURCE) decides what gets verified and where a fix goes. The report and the job result work the same way on every source. This guide covers each one and what the component produces.
The component adds one job, ironbee-verify, in the test stage. Its default rules: run it in exactly four kinds of pipeline: merge request pipelines, pushes to the default branch, schedules, and pipelines started by hand.
Merge request
The job runs in merge request pipelines (merge_request_event) by default.
What gets verified: the whole merge request.
Fixes: committed to the merge request’s source branch.
Report: a note on the merge request, updated in place on later runs, unless IronBee publishes the run on the merge request itself. See The report.
This is the most common pipeline and the recommended starting point.
One pipeline per push
If your project runs both branch and merge request pipelines, a push to a branch with an open merge request starts both. Keep it to one withworkflow:rules:
Push to the default branch
The job runs on a push to the default branch (push with $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH).
What gets verified: every commit in the push, from the push’s before commit (CI_COMMIT_BEFORE_SHA), or the commit against its parent when that base isn’t usable.
Fixes: committed to a new ironbee/fix-<sha7>-<pipeline_id> branch, with a merge request targeting the branch that was pushed. The fix merge request’s description is the report.
Use it alongside merge request pipelines to catch what broke after a merge.
Scheduled and manual pipelines
Create a pipeline schedule under Build > Pipeline schedules, for example0 9 * * 1 for every Monday at 09:00 UTC. A pipeline started by hand from Build > Pipelines > Run pipeline (web), through the API (api) or with a trigger token (trigger) runs the job too.
What gets verified:
- On IronBee: the latest commit against its parent.
- On your runner: the whole application.
No comment command
GitLab CI/CD has no pipeline trigger for a merge request note, so the GitHub Action’s/ironbee-verify comment has no equivalent in the component. To verify on demand, run a pipeline by hand.
Pipeline summary
Fixes need an Anthropic credential and a GitLab token. They also need
verification_apply_fix: 'true', the default. Without an Anthropic credential, a run on IronBee verifies and reports only. With verification_apply_fix: 'false', a run verifies and reports in both modes: on your runner, the agent reports what it finds and changes no file. A fix whose re-verification fails is not pushed.
Only what the fix changed is committed. On IronBee, the install and the build run before the fix, so what they write stays out of the commit. On your runner, the agent installs, builds and fixes in one session, so the component commits only after a verification failed and the agent verified again; that commit can also hold what the agent’s own install or build wrote. Files your app writes outside ignored paths while the fix runs count as changes too. With ironbee_exclude_files: 'false', IronBee’s setup files are committed with the fix.
Fix commits end in [skip ci] and are pushed with -o ci.skip. GitLab starts a pipeline for every push, and the push option skips only a branch pipeline; a merge request pipeline is skipped only by [skip ci]. Together they keep a fix from verifying itself again.
After a fix lands on a merge request branch, the merge request’s latest pipeline is a skipped one. On a project with Pipelines must succeed, the merge request can merge only once a new pipeline passes, unless Skipped pipelines are considered successful is on in the project’s merge settings.
Changing when the job runs
Redeclare the job’srules: in your own .gitlab-ci.yml. Redeclared rules: replace the component’s, so list every pipeline you want. For example, to run on merge requests and schedules only:
job_name input, redeclare the job under that name instead.
Turning automatic verification off
To verify only when someone asks for it with a manual pipeline, turn off verification in every other pipeline: merge requests, pushes and schedules. You have two ways to do it. In the job’srules:. GitLab evaluates them when it creates the pipeline, so a skipped pipeline costs nothing: no runner minutes, no clone, no image pull.
false.
With the verification_auto input. The component resolves to “nothing to do”, every step after the plan is skipped, and the job ends green in seconds.
before_script. Use the rules: when the job does expensive setup, and the input otherwise. Neither stops a manual pipeline.
The report
On a merge request, the component posts the report as a merge request note, and updates the note from an earlier run instead of adding another. On a push, schedule or manual pipeline, the report becomes the description of the fix merge request. When the project’s group is connected to IronBee, IronBee publishes a run on IronBee on the merge request itself, with inline comments and a summary. The component then posts no note, and theIRONBEE_PLATFORM_PUBLISHES output is true.
GitLab has no job summary. In every mode, the component prints the report in a collapsed IronBee Verification Report section of the job log, and saves it as report.md in the job’s artifacts.
A run on IronBee reports:
- the verdict and a link to the run in the IronBee Console
- the summary, and the Checks, Issues and Suggested fixes from the verdict
- after a fix, a link to the verification before the fix
- a No verification ran or No verdict banner, with the reason, when the run couldn’t produce a verdict
- the verdict, with the number of cycles when there was more than one
- each verification cycle, with its checks, issues and fixes, and a link to that verification in the console
- an early-exit banner, with a collapsible details block, when the agent stopped early (for example at
claude_code_max_turns) - a link to browse the job’s evidence artifacts
GITLAB_TOKEN, the report stays in the job log, and the component logs a warning.
The job result
The last step of the job fails it when the verification fails or ends without a verdict, so the job can hold a merge with Pipelines must succeed. The outputs are written as a dotenv report: a later job thatneeds: [ironbee-verify], or any job in a later stage, reads IRONBEE_VERDICT (pass, fail, not_applicable or unknown) and the other outputs as variables.
Forks
A merge request from a fork is refused, because a pipeline of the fork’s code must not run with your project’s credentials. The component says so at the plan step.What’s next?
Verifying your application
Choose the target: an app on the runner or a deployed URL.
Configuration
Every input and output, with defaults.