ironbee host makes from your machine what you would otherwise set up by hand on GitLab or Bitbucket for IronBee. Each command reads what’s there first, asks before each change, and changes nothing on a second run.
Use CLI 0.54.0 or newer. The commands act with your own tokens on GitLab or Bitbucket, and each token goes only to the host the command names.
ironbee host setup
For an administrator of a GitLab Self-Managed server or a GitLab Dedicated tenant. It prepares the instance for IronBee: the OAuth application, the instance’s settings and, on request, what the self-hosted runner and the components’ copies need. It ends by opening the console’s registration form, filled in. See GitLab Self-Managed and Dedicated. Paste a token of an administrator of the instance at the prompt:read -rs keeps the token out of your shell’s history.
Sign in
- To GitLab:
GITLAB_TOKEN, a personal access token of an administrator of the instance, with the scopeapi, andadmin_modewhere the instance has Admin Mode on. Withoutadmin_mode, GitLab hides that the token is an administrator’s, and the command stops. There’s no browser sign-in, since the application it would go through is what the command makes. The CLI neither keeps nor revokes the token: make it for the setup alone, with the nearest expiry date, and revoke it once the command has run. - To IronBee: the command reads IronBee’s address, its webhook host and the console’s address with your
ironbee login, orIRONBEE_API_KEY. Nothing of your instance reaches IronBee.
What it does
The host is the instance’s own name, as the registration takes it:https:// is taken off, with no path and no port. gitlab.com needs no setup, and the command says so. It checks that the instance runs GitLab 19.2 or newer and that the token’s user is an administrator, then takes these steps:
With
--runner, the command warns about an instance older than the runner’s GitLab 19.4, where ironbee runner setup stops until it’s upgraded, and still takes its steps.
The command changes neither token lifetimes, nor Disable personal access tokens, nor the Git access protocols: those stay the administrator’s choices. A setting GitLab’s API refuses, or answers without taking, is left to you, with GitLab’s words and its place in the Admin area. While an instance blocks all requests but its allowlist, GitLab refuses every settings change until the hosts named in its own settings’ addresses are on that list too, and its refusal names those settings.
The registration itself stays in the console: it’s an act on your IronBee account, by an owner or admin, and the CLI holds no credential that could make it. The form saves nothing until you click Register. Add a CA bundle there when a private authority signed the instance’s certificate.
The components’ copies
GitLab includes a component only from the instance the pipeline runs on, so your instance keeps a copy of each of IronBee’s components.--components <group> makes <group>/ironbee-gitlab, for the GitLab component, and <group>/ironbee-gitlab-runner, for the self-hosted runner:
- It makes the group and the two projects, public, where they’re absent. A subgroup’s parent must already exist.
- It changes the visibility of nothing it finds. The group and the runner’s copy must be public; the verification component’s copy may be internal.
- It pushes the branches and tags of
gitlab.com/ironbee-ai/ironbee-gitlabandgitlab.com/ironbee-ai/ironbee-gitlab-runnerinto the copies with your machine’s git, 2.31 or newer, moved tags included. It reads gitlab.com anonymously. - The push asks GitLab to start no pipeline: each project carries IronBee’s own release pipeline, which isn’t meant to run on your runners.
- A branch or tag the copy holds at another commit than gitlab.com is pushed with force, as a mirror’s is, so commits the copy has of its own on it are overwritten; one gitlab.com doesn’t have is left alone. Where the branch’s protection allows no force push, GitLab refuses it, and the command says so.
A private certificate authority
When a private authority signed your instance’s certificate:- The CLI is a Node program and doesn’t read your system’s trust store. Set
NODE_EXTRA_CA_CERTSto the authority’s PEM file. Node adds it to its own roots, so gitlab.com and IronBee are still trusted. - git, for the push of
--components, reads your system’s trust store, or the authority’s file for your instance alone:git config --global http.https://gitlab.acme.com/.sslCAInfo /path/to/ca.pem. The setting is global since the command pushes from a directory of its own.
Flags
With no terminal and no
--yes, each change is left undone, and the command says so.
ironbee host allow-address
For an Owner of a top-level group that restricts access by IP address, on GitLab Premium or Ultimate. It adds IronBee’s address to the group’s list, on gitlab.com unless you name your instance. The first line is for a group on gitlab.com, the second for a group on your instance:- It reads the group. Where the group’s list holds no address or range that covers IronBee’s address, it asks, then adds the address. A group that restricts no address is left as it is, and the command says so.
- Run it from an address the group already allows. The restriction holds for your own calls too, and GitLab answers a group as missing to any other address, which the command then says.
- GitLab keeps a group’s IP restriction on its top-level group, so a subgroup is refused.
- A Dedicated tenant’s own IP allowlist is kept in Switchboard, which no command reaches. See GitLab Dedicated.
ironbee login or IRONBEE_API_KEY, and signs in to GitLab as the group’s Owner:
- A token first.
GITLAB_TOKEN, a personal access token of yours on the host the command acts on, with the scopeapi. It goes to that host alone. - Else the browser. On gitlab.com, through IronBee’s own application. On your instance, through an OAuth application of that instance: name its ID with
--gitlab-client-id,IRONBEE_GITLAB_CLIENT_IDorrunner.gitlab.clientIdin the global config. The applicationironbee host setupmakes serves, since it holds the CLI’s redirect URI,http://127.0.0.1:7471/ironbee/gitlab-callback; one made by hand takes it as a second redirect URI. Port 7471 of your machine must be free, and the sign-in’s token is revoked when the command ends.
See Premium and Ultimate groups for the steps by hand.
ironbee host merge-check
For a repository admin on Bitbucket Cloud. On a Premium workspace, Bitbucket holds a merge on a build status only on a branch with two branch restrictions, which IronBee doesn’t set for you. The command adds them to the branch merges go into, each where it’s absent:- The builds check: “Minimum number of successful builds for the last commit with no failed builds and no in progress builds”, set to 1.
- The enforcement: “Prevent a merge with unresolved merge checks”. Without it, the checks only warn.
--branch, the command works on the repository’s default branch; the last line names another branch:
BITBUCKET_TOKEN is an Atlassian API token of yours, the one the ironbee runner commands take, with the scopes read:repository:bitbucket and admin:repository:bitbucket. Where it isn’t set, the command asks for it on a terminal, typed unseen; with no terminal, it stops. It sends the token to api.bitbucket.org alone, and makes no call to IronBee.
What it does
Before it asks about the enforcement, the command names every other merge check of the branch, because the enforcement makes each of them hold a merge too: a number of approvals, no changes requested, every task completed, and so on. A custom merge check an app defines is set up elsewhere, and the command doesn’t read it. Where the branch has “No changes are requested” without “Reset requested changes when the source branch is modified”, it says that a request for changes then holds a merge even after the fix. IronBee’s review never requests changes, so that check only reacts to people’s requests. The command doesn’t add that reset: a repository admin ticks Reset requested changes when the source branch is modified in the same place.
- It adds and never takes away. A restriction that’s there isn’t changed, a second run changes nothing and says so, and no flag removes one. Remove a restriction in Repository settings > Branch restrictions, whoever set it.
- It reads no plan, so its words say both: on a Premium workspace the checks hold a merge, and on Free and Standard they only warn. Where Bitbucket refuses the enforcement, the command adds that the workspace’s plan can be why.
- A change it doesn’t make is said: one you declined, or one it can’t ask about with no terminal and no
--yes, with where a repository admin makes it by hand. - A refusal is Bitbucket’s, in its words. A token without
admin:repository:bitbucketis refused at the first read of the branch’s restrictions, before anything is written, and the command stops there. From an address your workspace’s IP allowlist doesn’t hold, Bitbucket answers “To access this repository, an admin must whitelist your IP.”; run the command from an address on the list. See Bitbucket Cloud Premium.
Exit codes
What’s next?
GitLab Self-Managed and Dedicated
Register your instance and connect its groups.
Merges on Bitbucket
What holds a merge once the merge checks are enforced.
Self-hosted runner
Set up the self-hosted runner with
ironbee runner.Authentication
Sign in with
ironbee login, or use an API key.