Skip to main content
Keep your code-managed flows in a GitLab repository, self-hosted or on gitlab.com. A CI job sends the repository’s .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.
When a file is invalid, the job fails and prints each error with its file and line.

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 .gitlab-ci.yml. It needs the BugRadar CLI 0.9.19 or later, which pip install BugRadar installs.
.gitlab-ci.yml
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 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
GitLab checks out a commit rather than a branch, so pass --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 predefined CI_* 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, and NO_PROXY if 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_FILE to a PEM file that holds that CA, or SSL_CERT_DIR to 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 BugRadar already installed and no pip install line. 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 as https://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.
Everything in Set up applies as on gitlab.com: a masked, unprotected 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

  • --force applies 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-empty sends a .BugRadar/ folder that holds no *.flow.yaml files. 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 the BugRadar_API_URL variable, 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, run BugRadar 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, or holds 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 …, or File 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 --force from merge request jobs.
  • --api-url must be an http or https URL: fix --api-url or BugRadar_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 with Failed 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 run without --local or --cloud reads from GitHub. For a GitLab repository, use BugRadar 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.

Next Steps