.BugRadar/ folder to BugRadar. BugRadar never connects to your GitLab server.
- On the default branch, the job updates your tests in BugRadar, as a push to the default branch does on GitHub.
- In a merge request, the job checks the files and reports errors. Nothing is saved.
Set up
1
Add your API key to GitLab
Create an API key with
BugRadar keys create or in Settings → API Keys. In your GitLab project, open Settings → CI/CD → Variables and add BugRadar_API_KEY with the key as its value.Mark it Masked. Leave Protect variable unchecked: GitLab withholds protected variables from merge request pipelines on unprotected branches, so those jobs would fail.2
Add the job to .gitlab-ci.yml
Add this job to This job runs in merge request pipelines. If your project’s other jobs run only in branch pipelines, each push to a branch with an open merge request starts a second pipeline that holds only this job, and a “Pipelines must succeed” check can pass on it alone. To avoid that, set
.gitlab-ci.yml. It needs the BugRadar CLI 0.9.19 or later, which pip install BugRadar installs..gitlab-ci.yml
workflow:rules so your project uses merge request pipelines, as in GitLab’s switch between branch pipelines and merge request pipelines example.3
Push to the default branch
The first default-branch run connects the project to your BugRadar organization. Your tests appear on the Flows page, read-only.
Merge requests from forks run in the fork and don’t receive your project’s variables, so
BugRadar flows sync stops with “BugRadar_API_KEY is not set”. Fork changes are checked when they reach your default branch.Run a merge request’s tests
BugRadar flows sync only checks merge request files. To run them, add a job that runs the merge request’s .BugRadar/ on BugRadar’s cloud devices:
.gitlab-ci.yml
--branch or --app-build-id. --branch picks the newest app build uploaded from that branch, and --app-build-id picks a build directly. The app comes from .BugRadar/config.yaml or from flags, as in Cloud runs.
The job starts the runs and prints a link to each, then a batch id. It does not wait for results. To make the job wait and fail when a flow fails, add --wait (see Waiting for the result).
Self-hosted GitLab
Add the job from Set up, then check the points below. BugRadar never connects to your GitLab instance. Your runner connects out to BugRadar, and the CLI reads only GitLab CI’s predefinedCI_* variables, so the jobs above need GitLab 13.4 or later.
For a runner without Docker Hub or PyPI, the job pulls Python from your internal registry and installs from your PyPI mirror. The hosts are placeholders; use your own:
.gitlab-ci.yml
- Network access. Runners need outbound HTTPS (port 443) to
backend.usebugradar.com. - Proxy. Set
HTTPS_PROXY, andNO_PROXYif needed, as a CI/CD variable or in the runner’s environment. The CLI sends its requests through that proxy. - TLS inspection. If your proxy re-signs HTTPS traffic with an internal certificate authority, set
SSL_CERT_FILEto a PEM file that holds that CA, orSSL_CERT_DIRto a folder of hashed certificates. Either replaces the default trusted CAs, so include any others the job needs. - No access to Docker Hub or PyPI. Use the job above, or an image with
BugRadaralready installed and nopip installline. The job still needs to reach BugRadar. - Source links. Open in GitLab links in the dashboard use your project’s address from
CI_PROJECT_URL, such ashttps://gitlab.example.internal/group/project. They open only for people who can reach your GitLab, for example on your network or VPN.http://addresses work too.
BugRadar_API_KEY, merge request pipelines, the workflow:rules advice, and merge requests from forks.
What the job reports
One invalid file blocks the whole upload: nothing changes until every file is valid, as on GitHub.
Flags
--forceapplies this commit even when BugRadar already synced a newer one. Use it only when this commit’s timestamp is wrong. It works on the default branch only. In a merge request pipeline the CLI refuses it and sends nothing.--allow-emptysends a.BugRadar/folder that holds no*.flow.yamlfiles. On the default branch, this removes every test the project synced. Use it only to delete every test on purpose. Without the flag, the CLI refuses such a folder. A missing.BugRadar/folder is refused even with the flag.--api-url, or theBugRadar_API_URLvariable, sets the BugRadar server. Leave it unset unless BugRadar gave you a different URL.
Exit codes
Troubleshooting
The job exits with code 2
The CLI stopped before sending anything. The message names the fix:runs only inside a GitLab CI job: run it as a GitLab CI job. To check files locally, runBugRadar flows validate.GitLab CI did not set …: run the job in a default-branch pipeline or a merge request pipeline. If the message adds “Tag pipelines cannot sync.”, remove the job from tag pipelines.BugRadar_API_KEY is not set: add the variable, masked and not protected.The BugRadar API key contains spaces or line breaks: copy the key into the variable again, without them.No .BugRadar/ folder, orholds no flow files: commit.BugRadar/at the repository root, and check that the job checks out the repository.holds symlinks, or.BugRadar is a symlink: replace each symlink with the file or folder it points to.Could not read …, orFile is not valid UTF-8 text: the job cannot read a file in.BugRadar/. Fix or remove the file the message names.--force applies only to default-branch pipelines.: remove--forcefrom merge request jobs.--api-url must be an http or https URL: fix--api-urlorBugRadar_API_URL.
BugRadar refused the upload (HTTP …)
The job exits with code 1 and prints BugRadar’s reason.
If the job says
BugRadar answered with an unknown status, update the CLI. The job above installs the newest version on each run, so re-run it.
BugRadar may have applied this upload
The connection broke after the upload was sent, so the job cannot tell whether it was applied. Re-run the job. Re-sending the same commit is safe. The CLI already retries once, 5 seconds later, when BugRadar is briefly unavailable or the upload never reached it. If it still fails withFailed to reach …, nothing was applied: check your runner’s network access to BugRadar.
Limits
.BugRadar/must be at the repository root. Root directory for monorepos is GitHub-only.- GitLab-synced tests are read-only in the dashboard, and their source links open GitLab.
- Branch runs need GitHub. The dashboard hides branch choices for GitLab repositories, and
BugRadar runwithout--localor--cloudreads from GitHub. For a GitLab repository, useBugRadar flows run --cloud. - Results appear in the job log, not as merge request comments or commit statuses.
- There is no resync button. Re-run the default-branch pipeline instead.