code-review, in IronBee’s project gitlab.com/ironbee-ai/ironbee-gitlab-runner, listed in GitLab’s CI/CD Catalog. A project of yours, the runner project, includes the component and nothing else. Your reviewed projects send their merge request and comment events to the runner project’s pipeline trigger through webhooks, and its pipelines run IronBee’s reviewer with your own model. It publishes its review on the merge request, and writes a status named Code Review Result into the merge request’s pipeline, which holds a merge where you ask it to.
This page explains the setup and what to decide. The component’s project is the full reference, with every input, variable and message: ironbee-ai/ironbee-gitlab-runner.
Where it runs
- gitlab.com.
- GitLab Dedicated and GitLab Self-Managed 19.4 or later, Enterprise or Community Edition, on any tier, including an instance IronBee can’t reach from the internet. See GitLab Dedicated and Self-Managed.
How it fits together
Nothing changes in a reviewed project’s own
.gitlab-ci.yml. The secrets live only in the runner project, as protected variables, out of reach of a merge request’s author, and one runner project can serve many projects.
Where the runner project goes. The runner project’s Maintainers and Owners, directly or through its groups, manage its variables. Put it where those are the people who administer the reviewer: if the reviewed projects’ group has Maintainers who don’t, make a top-level group of its own for the runner project first. gitlab.com makes no top-level group through its API, so that step is yours.
Before you start
- The runner is enabled on your account, and you have the account’s API key and a registry token. See What you need.
- A top-level group on gitlab.com that you’re an Owner of: only its Owner can create the group’s service account. On gitlab.com, that Owner verifies their identity once before the group’s first service account.
- The Maintainer role, or Owner, on each project to review: its webhooks need it.
- A model, and its key where it needs one.
Set it up
ironbee runner setup takes every step from your machine, signed in to GitLab as you. Export the secrets first, or let the command ask for them:
GITLAB_TOKEN to a short-lived personal access token of yours with the api scope.
It registers the projects with IronBee, which makes each one’s project in the console, then makes what How it fits together lists, among them the webhooks “IronBee merge requests” and “IronBee comments”. Before it goes on with the runner project, it lists everyone who reaches its secrets and asks you to confirm. It ends with the probe, one delivery that must run IronBee’s images end to end, so a registry token that can’t pull, runner tags no runner has or a mistyped key shows up now, not at the first merge request. For each step and flag, ironbee runner add and ironbee runner check, see ironbee runner on GitLab.
These stay yours: the browser approval, the identity verification on gitlab.com, a top-level group of its own for the runner project where you need one, and gating merges.
To take the same steps by hand in GitLab’s pages, see the component’s Setup.
The runner project’s file
projectslists the reviewed projects’ paths, one a line. They’re the only projects a run acts on.- Keep nothing else in the file: a
workflow:, adefault:or a job of your own would reach the component’s jobs. @v1follows the newest 1.x release. The setup writes the exact latest release instead, whichironbee runner setup --updatemoves.
model-provider, model-url, model-name, model-ca-certificate, model-prefix, model-max-output and aws-region. Beside them, runner-tags names your own runner, knowledge-repository your rules repository, and ironbee-run-reports turns the run reports off. See the component’s Inputs.
The variables
The runner project’s own CI/CD variables, each protected, never set on its group:The service account
The reviewer reads your merge requests and writes its reviews, replies and status as a service account of your top-level group, with a personal access token stored in the runner project. IronBee holds no GitLab credential of yours.- Its name: “IronBee code review runner”, username
ironbee-runner-<group path>unless you name another with--service-account. Give it a name of its own, never that of the IronBee account in a group connected to IronBee’s cloud, which is another reviewer. - People address it as
@ironbee-ai, or by its username, which GitLab’s autocomplete offers. - Its token has the
apiscope and the longest life the group allows, a year at most. GitLab mails its expiry notices only to an address you give with--notify-email.ironbee runner check --rotate-tokenreplaces it.
Where the jobs run
- gitlab.com’s runners work for a model reachable from the internet.
- A model inside your network needs a runner of yours there. Name its tags in the
runner-tagsinput, and every job of the component runs on it. - Your runner’s executor runs a job’s image: Docker, Docker Autoscaler or Kubernetes, on
amd64orarm64. The shell executor can’t run these jobs. - The network: the jobs connect to GitLab, your model’s endpoint and IronBee’s API (
api.service.ironbee.ai), and the runner pulls from Docker Hub. If you turn on Jev, they also connect to Typesafe’s endpoint,api.typesafe.ai.
Compute minutes. On gitlab.com’s runners, every job spends the compute minutes of the runner project’s own top-level group, whatever plan the reviewed projects’ group has. Every delivery runs a decide job, the reviewer’s own notes included, and the sweep adds a job at each interval. A group that has spent its minutes runs no job at all, reviews included. A runner of yours spends none. See the component’s Where the jobs run.
The trigger budget
On gitlab.com, one runner project can create at most 25 pipelines a minute through its triggers, a gitlab.com limit. Every event a hook sends is one, whether or not it’s for the reviewer, and most are the reviewer’s own notes: a round of eight comments is about ten deliveries. Past the limit, a delivery is lost, and a hook that fails four times in a row is turned off for a while. A team whose projects often review several merge requests at once splits them among more runner projects. Self-Managed GitLab sets no such limit by default. See the component’s The trigger budget.Gating merges
The reviewer writes the Code Review Result status into the merge request’s head pipeline, the one GitLab’s Pipelines must succeed reads. Whether it holds a merge is up to you:
Block merges is the console’s code review setting for GitLab repositories, on the account’s Code review settings as Block merges on GitLab and on each GitLab repository’s, and Block merging when sets which findings block. See Code review settings.
To gate
- Turn on Pipelines must succeed in each project’s Settings > Merge requests > Merge checks.
- Turn on Block merges on GitLab in the account’s code review settings in the console, or Block merges in the project’s.
- Turn on All threads must be resolved beside them, recommended. A finding the reviewer placed on the diff is a thread, and a thread holds the merge whatever becomes of a pipeline.
- Keep a working sweep. The setup makes its schedule when a project gates at setup time. If you turn gating on later, run
ironbee runner check --fix, which makes the schedule and plays it once.
The running status
Where you gate, a run that begins a review holds the merge while it works: the merge request’s pipeline shows the Code Review Result job running, “Review under way”. The runner writes it only while a sweep job of the runner project has succeeded in the last three hours, since a running status a dead run leaves is settled by the sweep. A team that gates waits for the review, minutes as a rule.The sweep
The sweep is a scheduled pipeline of the runner project, every ten minutes by default and never less often than hourly, made only where a project gates its merges. It finds open merge requests whose head pipeline holds no status of the reviewer’s, such as after a lost delivery or a pipeline started by hand, and has each one reviewed or its conclusion written again. It also settles a running status a dead run left. GitLab keeps a schedule no more often than the plan of the runner project’s top-level group allows, which on gitlab.com’s Free tier is hourly. See the component’s The sweep.What the status is worth
The status reflects the findings nobody who counts has turned down. The merge request’s author can close a finding with a reply or a thumbs-down, and someone with the Developer role can resolve a thread,retract, or pause and then push.
- A run that never began its review holds nothing until the sweep finds its head: an image that couldn’t be pulled, a lost delivery, or a newer pipeline of the same commit. The status is a signal that can be late, not a lock.
- A merge request from a protected branch, such as
developintomain, is reviewed with no status, since GitLab takes a status into that pipeline only from someone who may push or merge there. Its open threads still hold it under All threads must be resolved. See the component’s Protected source branches to opt in.
On the merge request
The reviewer publishes each round whole: its comments, then the review’s note. With Pull request summary on, the summary is a note of its own, never the description. A later push starts a follow-up round that reads only what changed since.- Who may command: people with the Developer role or above. The service account’s username works as well as
@ironbee-ai. - Replies: a reply on one of the reviewer’s threads, from the merge request’s author or a member with the Developer role or above, gets an answer while Answer questions is on.
- Turned down or resolved: a reply that turns a finding down, and a thread someone resolves, count at the next review that reads the merge request again.
- Bots: the reviewer’s own notes and a bot’s notes start nothing.
GitLab Dedicated and Self-Managed
The runner serves projects on a GitLab Dedicated tenant and on a GitLab Self-Managed server running GitLab 19.4 or later. There’s no host to register in IronBee’s console, no IronBee address to let in, and no IronBee plan asked: the runner follows its own license. An instance IronBee can’t reach from the internet is served when its runners reach IronBee’s API, Docker Hub and your model.
Your copy of the component. GitLab includes a component only from the instance the pipeline runs on, so the runner project includes a copy on your instance. It must be public: the pipelines run as the trigger owner, a service account, which can’t read an internal or private project it isn’t a member of. Make it with a pull mirror where your tier has one, or by pushing the branches and tags, with
-o ci.skip. Bring it up to date for each new release.
The administrator’s steps. An administrator of the instance allows top-level group Owners to create service accounts, and adds the instance’s own host name to the hosts webhooks may reach. Where the instance keeps the Public level from its users, an administrator also makes your copy public. ironbee host setup <host> --runner --components <group> takes the first two steps and makes the group and the copy, public, where they’re absent. It changes the visibility of nothing it finds: a group that exists must already be public, or the step stops and asks you to make it public or name another group. See ironbee host setup.
With the setup command on your instance, set GITLAB_HOST to it and GITLAB_TOKEN to a token of yours there, or name the instance’s OAuth application for the browser sign-in. Add --component <your copy's path>@<tag>. See ironbee runner.
@ironbee-ai on your instance notifies a user or group of that name, where one exists. Address the reviewer by its service account’s username there.
This release doesn’t serve:
- an instance served under a path, such as
https://acme.com/gitlab, or on a port other than 443 - an instance named by an IP address, or by a single label with no dot
- GitLab older than 19.4
- an instance that lets no project be public
- an image registry other than Docker Hub, except a mirror of Docker Hub that keeps the image’s reference and digest
- GitLab Dedicated for Government
Troubleshooting
Look first at the Code Review Result job in the merge request’s pipeline, then at the runner project’s Build > Pipelines. Every delivery is a pipeline there: thedecide job’s log says in one line, starting with decide:, what it made of the delivery, and the review job’s log says what the runner read and decided. A reviewed project’s Settings > Webhooks shows whether GitLab turned a hook off, and each delivery’s answer. Then run ironbee runner check, which reads the whole setup and ends with the probe.
The component’s Troubleshooting lists every message.
What’s next?
ironbee runner
Set up, extend and check a runner from your machine.
Self-hosted runner overview
The license, models, settings and what reaches IronBee.