Quick start

This page takes you from nothing to a first analysis in about 15 minutes. You need Linux, macOS or WSL, with Docker, Compose v2 and openssl. Everything runs from the qualor/server and qualor/scanner images on Docker Hub.

The fastest path is Add repositories: connect GitHub or GitLab, tick your repositories, and merge one merge request in each. The manual path follows it, for any other CI system or when you want to see each step.

1. Start the server

Create a directory:

mkdir -p ~/qualor && cd ~/qualor

Save the compose file from Install the server there as compose.yml. Then create the settings with generated secrets, and start:

umask 077
cat > .env <<EOF
QUALOR_VERSION=0.15
QUALOR_SECRET_KEY=$(openssl rand -hex 32)
QUALOR_BOOTSTRAP_ADMIN_PASSWORD=$(openssl rand -hex 16)
EOF
docker compose up -d
docker compose ps          # wait until "server" is healthy (15–30 s)
grep BOOTSTRAP .env        # the admin password for the first sign-in

Open http://127.0.0.1:8080 and sign in as admin with that password. Then change it: open the menu under your name at the top right and choose Change password. Forgot password? works only once Qualor can send email (Forgotten passwords).

The server listens on 127.0.0.1 only. To reach it from other machines, put TLS in front of it (Reverse proxy and TLS).

Fastest path: Add repositories

An organization admin does this in the UI. Qualor creates the projects and sets up CI for them.

  1. Connect GitHub (GitHub) or GitLab (GitLab). For CI setup, also set QUALOR_PUBLIC_URL on the server, turn on Allow Qualor to set up CI on a GitLab connection, or give a GitHub App Contents, Workflows and Secrets (each Read and write).
  2. Open Projects → Add repositories, pick the connection and tick up to 50 repositories. Repositories that already have a project are marked. An archived repository cannot be picked.
  3. Leave Set up CI with a merge request on, and start. Qualor creates a project for each repository, with the repository path as its key and the organization’s default gate and profiles. A project that already has that key and no repository is mapped to the repository and keeps its history.
  4. Each merge request’s own pipeline runs the first analysis. Merge it to analyse every push to the default branch.

Qualor opens a merge request only when it can edit the CI files safely. Otherwise, and when you turn CI setup off, it shows the snippet to add and the project token, once. Copy the token then: it is not shown again. What the merge requests contain, and how to undo them, is in GitHub and GitLab.

The setup checklist

Organization admins see Set up Qualor in a corner of the screen. Its steps are Connect GitHub or GitLab, Add repositories, Get the first analysis, Turn on AI review and Invite your team. Each step ticks by itself from the server’s state and links to the page where you do it. Collapse the list, or choose Don’t show again to hide it for good. When only a server admin can set up an AI provider, the AI step says so and does not count.

Or by hand

The steps below do the same without Add repositories. Use them for CI systems other than GitHub and GitLab, or to see each part.

2. Pull the scanner

docker pull qualor/scanner:0.15

It is about 4.1 GB, 1.4 GB of which is Trivy’s vulnerability database. CI runners pull it the same way.

3. Create a project and a token

  1. Projects → New project. The Key identifies the project in every scan. By default the scanner uses the CI project path as the key: CI_PROJECT_PATH on GitLab (group/app), GITHUB_REPOSITORY on GitHub (owner/repo). Use the same value here and you need no config file.
  2. The main branch is main, and analyses of every other branch are compared with it. If your default branch has another name, such as master, change it before the first scan in Project → Settings → Main branch (Projects).
  3. Settings → Access tokens → New token, with the scope Upload analyses. Copy the token: it is shown only once.

For CI, a project analysis token is safer: it can only upload to, and read exports of, its own project.

4. Run a first scan locally

From the root of any git repository you want to analyse:

cd /path/to/your/repo
docker run --rm --network host \
  -v "$PWD":/src -w /src \
  -e QUALOR_URL=http://127.0.0.1:8080 \
  -e QUALOR_TOKEN=<token> \
  -e QUALOR_PROJECT_KEY=<project key> \
  qualor/scanner:0.15 scan

--network host lets the container reach the server on 127.0.0.1, on Linux. With Docker Desktop, use QUALOR_URL=http://host.docker.internal:8080 instead.

The scanner runs the analyzers that fit your code, uploads the report and prints the gate verdict. A first analysis of the main branch has no new code, so it passes the default gate. Open the project in the UI to see its issues, coverage, duplication and size.

Some analyzers need the project prepared first. For JavaScript or TypeScript, install the dependencies (npm ci): ESLint runs from the project’s own node_modules, with its own config. For Java, build first (mvn -DskipTests package): SpotBugs reads compiled classes. See Languages and analyzers.

5. Put it in CI

From then on, every merge request or pull request gets a verdict on the code it changes, and the pipeline fails when the gate fails. Once the GitLab or GitHub connection is set up, reviewers also see a summary comment and comments on the changed lines.

What next