ironbee runner sets up IronBee’s self-hosted runner from your machine: code review in your own GitHub Actions, GitLab CI/CD or Bitbucket Pipelines, with your own model. It signs in to your host as you, registers the repositories with IronBee, stores the secrets in your CI and adds the runner’s file.
On GitHub, setup signs in through gh, stores the secrets and adds the workflow file by a pull request. On GitLab, it signs in as the top-level group’s Owner and makes everything for the projects named. On Bitbucket, it acts with BITBUCKET_TOKEN: it turns Pipelines on, writes the variables and the block, sets up the trigger app and runs the probe. The example sets up each host, then adds a project on GitLab, checks GitHub, where --fix would also repair what the check finds, and checks Bitbucket with the probe:
Every step also has a by-hand version in the runner’s own guide, and a setup made by hand is the same as one the command made:
check reads either. Each step first reads what exists and changes only what’s missing, so you can run a command again after a failure.
Before you start
- CLI 0.54.0 or later, and Node.js 22 or later.
- The self-hosted runner enabled on your IronBee account, and a registry token from IronBee for the runner’s image. See What you need.
- Your account’s API key, from the console’s Account page. The command registers the repositories with it.
- The rights the host’s section below lists, and its sign-in.
The host
--host github, --host gitlab or --host bitbucket names the host. Without it, the command takes the host from this directory’s git remote, and asks when it can’t tell.
- An SSH remote’s host is the one its
~/.ssh/configalias reaches, asssh -Greads it. - A remote on a host other than github.com, gitlab.com or bitbucket.org is GitHub or GitLab when it’s one of your account’s GitHub or GitLab hosts. The command reads that list from IronBee with
IRONBEE_API_KEY, else yourironbee loginsign-in, and keeps it for a day. - GitHub’s host is the remote’s, else
GH_HOST, else github.com. GitLab’s is the remote’s, elseGITLAB_HOST, else gitlab.com.
What it’s given
The secrets
Each secret comes from its environment variable, or is asked for in a terminal and typed unseen. The command writes none of them to disk, prints none of them, and sends none to IronBee: they go from your machine into your CI’s secrets or variables.
A value already in your CI is treated the host’s way. On GitHub, a secret that’s there is kept. On GitLab, a value you give is written over the variable that’s there, and a variable you give no value for is kept. On Bitbucket, a variable that’s there is left as it is, since a secured value can’t be read back.
The flags every host takes
What a flag doesn’t give, the command asks for in a terminal. Without a terminal, it stops and names the flag.
The command calls IronBee only to register the repositories and to read your account’s hosts. It uses the CLI’s API address,
IRONBEE_API_URL or the global config’s. When that address isn’t the default, a file it writes names it in ironbee-api-url on GitHub and GitLab, and on Bitbucket it writes the Pipelines variable IRONBEE_API_URL with the other variables. Nothing is written to disk but the account’s list of hosts.
On GitHub
gh: gh auth login, or GH_TOKEN in the environment. The command stores no GitHub credential and sends none to IronBee. You need to administer each repository’s Actions secrets, and to push a workflow file there, which takes the token’s workflow scope.
What
setup does, in this order:
- Registers the repositories with IronBee. A refusal, such as the runner not enabled, the license ended or suspended, or a repository IronBee’s cloud reviews, ends the command before anything changes on GitHub.
- Stores the secrets through
gh, each repository’s own by default. With--org-secrets, they’re the organization’s: the command checks that your sign-in has theadmin:orgscope (gh auth refresh -s admin:org) and that the repositories can read organization secrets, which a private repository on GitHub Free can’t. A secret that’s there is never set again: the repositories named are added to its list. - Adds the workflow file,
.github/workflows/ironbee-review.yml, at the release, with the model’s inputs and the repository’s default branch in itspushtrigger. By default it’s on a branch of its own,ironbee/runner-setup, with a pull request, which is the first one reviewed. With--direct, it’s committed to the default branch. A file that’s there is left as it is, and--updatemoves only the release it names. - Prints what it made and kept, and that Code Review Result becomes a required check through your branch protection, which the command doesn’t set.
ironbee runner check reads, for each repository: the workflow file on the default branch and its release against the latest; that the secrets it passes exist, by name; that GitHub Actions is on and may call the runner’s workflow; the registration; and whether Code Review Result is required, as information. Your own GitHub App, a self-hosted runner, the rules repository’s content and branch protection aren’t the command’s.
GitHub Enterprise
On GHE.com and GitHub Enterprise Server, the host is the clone’s remote, orGH_HOST with --host github. Every gh call goes to that host, and each repository is registered as <host>:owner/name.
--component <owner>/<name>@<tag>names your copy of the runner’s repository on that host, and its release.--runs-onis required on a server, which has no hosted runners. Add--github-ca-certificate <file>when a private authority signed the server’s certificate.IRONBEE_RUNNER_TOKEN, a read-only token that can read your copy, is asked for and stored as an Actions secret and a Dependabot secret. On github.com it’s asked for too, for a copy that isn’t public. On GHE.com, a rules repository needsIRONBEE_KNOWLEDGE_TOKEN.- On a server, the file calls the workflow without a queue, names your copy in
runner-repository, and grantsactions: write.
check also reads your copy’s visibility and Actions access, and says when a file lacks what its host needs. See GitHub Enterprise.
On GitLab
- In the browser, the default: the command opens GitLab’s authorization page for IronBee’s OAuth application, with the
apiscope, and waits up to five minutes. GitLab answers onhttp://127.0.0.1:7471/ironbee/gitlab-callback, so port 7471 must be free. The token stays in the command’s memory and is revoked when it ends. GITLAB_TOKEN, for a machine with no browser: a personal access token of yours with theapiscope. The command neither stores nor revokes it, so make a short-lived one and revoke it after.
What
setup does, in this order. The order never leaves a trigger on a runner project that isn’t locked down:
- Registers the projects with IronBee. A refusal ends the command before anything is made on GitLab.
- The service account: found or made in the group, and made a Developer of each reviewed project and of the rules repository.
- The runner project: found or made. The command lists everyone who is or would be a Maintainer or Owner of it, and every protected branch or tag rule that admits less than a Maintainer. It corrects the project’s own rules when you agree, and stops unless you confirm the rest. Then it makes the project private, lets no one use pipeline variables, protects the default branch for Maintainers alone, and turns off auto-cancel.
- The variables, protected, and masked and hidden where GitLab can mask the value. The service account’s token is made here and written in the same step.
- The file,
.gitlab-ci.yml, with the component’s include. GitLab’s CI lint checks it before it’s committed. A file that’s there keeps its release and gains the new projects’ lines. - The trigger owner, the triggers and the sweep. A trigger for each project; right after the first one, a call that checks the runner project refuses pipeline variables. The sweep’s schedule is made only where a project gates its merges, and played once.
- The webhooks on each reviewed project, or the group’s pair with
--group-hooks. - The probe: one delivery that must run IronBee’s images end to end. It starts no review and counts no developer.
ironbee runner add <project> takes the same steps for the projects named, and needs only IRONBEE_API_KEY of the secrets. Give --group when the runner project is in a personal namespace.
ironbee runner check --runner-project <namespace/name> reads the runner project’s settings, the variables’ names, the file through GitLab’s CI lint and its release against the latest, each project’s webhooks, the service account’s memberships and token, the triggers, the sweep and each registration, and ends with the probe. Run it after any change made by hand to the runner project.
GitLab Dedicated and Self-Managed
On your own instance, the host is the clone’s remote, orGITLAB_HOST with --host gitlab. Every GitLab call goes to that instance, which must run GitLab 19.4 or later, and each project is registered as <host>:<path>.
- The sign-in is a token first.
GITLAB_TOKEN, a token of yours on the instance with theapiscope, is used there only whenGITLAB_HOSTnames the instance. Otherwise the browser signs in through an OAuth application of the instance: name it with--gitlab-client-id,IRONBEE_GITLAB_CLIENT_IDor therunner.gitlab.clientIdconfig key. It’s not confidential, has theapiscope, and redirects tohttp://127.0.0.1:7471/ironbee/gitlab-callback.ironbee host setupmakes one. --component <group>/<project>@<tag>names your public copy of the component and its release, from 1.0.0 on.setup,addandcheck --fixrequire it, and refuse--version.- The service account: where the instance lets only administrators create one, the command shows GitLab’s refusal and the setting that lets an Owner do it.
- Its token is asked for 364 days, and where the instance refuses that, for 180, 90, 60, 30 or 7.
- One webhook is tested with a push event, which reviews nothing, since an instance refuses its webhooks’ calls to itself until an administrator allows them.
- A private certificate authority: set
NODE_EXTRA_CA_CERTSto its file on your machine.
ironbee host setup. See also GitLab Dedicated and Self-Managed.
On Bitbucket
BITBUCKET_TOKEN, an Atlassian API token of yours, or asked and typed unseen. Make it at id.atlassian.com for the setup, with the nearest expiry date, and revoke it after. The command never stores it or sends it to IronBee. It needs these scopes, each ending in :bitbucket: read:repository, write:repository, admin:repository, read:pullrequest, write:pullrequest, read:pipeline, write:pipeline and admin:pipeline. Before anything changes, the command tries what each step needs and names any scope the token lacks.
You need the admin permission on each repository, and to be a workspace admin for --workspace-variables or the trigger app.
The trigger app’s step needs Node.js, npm, Atlassian’s Forge CLI (npm install -g @forge/cli) and a developer space, made once in Atlassian’s developer console. It signs in to Forge with FORGE_EMAIL and FORGE_API_TOKEN, your Atlassian account’s email and an API token of it, or with a forge login. Revoke that token when the command has ended. When one of these is missing, the command names it and goes on without the app.
What
setup does, in this order:
- Registers the repositories with IronBee. A refusal ends the command before anything changes on Bitbucket.
- Turns Pipelines on where it’s off. When Bitbucket refuses, for example because it asks your account for two-step verification, the command says to turn it on in the repository’s settings, and goes on.
- Writes the variables, the secrets secured. A value of more than one line is written as
base64:followed by the value in base64. - Adds the block to
bitbucket-pipelines.ymlas text, in your file’s own indentation, keeping every other byte, and reads the result back before it’s written. A file that exists is always changed by a pull request from the branchironbee-runner-setup.--updatereplaces a block’s lines whole, keeping itsruns-on. - Sets up the trigger app, once for the workspace. It says whose the app will be and asks you to go on, then fetches the release’s app source, runs
npm ci --ignore-scripts, registers the app in your developer space, records it as the workspace variableIRONBEE_TRIGGER_APPat once, deploys it to Forge’s production environment and installs it on the workspace. - Reports what it made, kept and found, never a secret, and what gates a merge in each repository.
ironbee runner check --probe.
ironbee runner check --repos <list> reads the block and its release against the latest, Pipelines, the variables by name, the registration, the trigger app and, signed in to Forge, its installation, and the default branch’s merge checks, as information. --fix repairs what the steps make, and --probe runs the probe.
Code Review Result holds a merge only on Bitbucket Premium, with the branch’s merge checks set. ironbee host merge-check sets them; see ironbee host merge-check. check names it where they’re missing.
Environment variables
Exit codes
What’s next?
Self-hosted runner
What the runner is, its license, models and settings.
Host setup
Prepare a GitLab instance, or set a Bitbucket branch’s merge checks.