# Releases and versions Qualor records each release of a project as a **version**: a label and the release's dependency list. A scan in a tag pipeline records it. The GitLab component and the GitHub workflow templates run that scan on every tag. A project's rules decide which of its versions are tracked. The settings panel, the **Dependencies** tab and the API show which ones are. The server checks the tracked ones for vulnerabilities ([Dependency vulnerabilities](https://qualor.dev/docs/dependency-vulnerabilities.md)). ## Record a version on each tag ### GitLab The job of the [CI/CD component](https://qualor.dev/docs/gitlab.md#with-the-cicd-component-recommended) runs on tags. A [job without the component](https://qualor.dev/docs/gitlab.md#without-the-component) needs this rule among its `rules`: ```yaml rules: - if: $CI_COMMIT_TAG ``` ### GitHub The workflows of [GitHub](https://qualor.dev/docs/github.md#2-the-workflow) run on tags. If your workflow has no `tags` under `push`, add them: ```yaml on: push: tags: ['**'] ``` The tag scan uses the job's token and settings. It needs nothing else. ### Other CI systems Pass the tag with `--tag`: ```sh qualor scan --tag "$TAG_NAME" ``` - `--tag` cannot be combined with `--branch` or `--mr`. - The name has at most 255 characters, and git must accept it as a tag name. ### Releases you shipped earlier Check out each release tag and scan it, as in [A local scan](https://qualor.dev/docs/other-ci.md#a-local-scan): ```sh for tag in v2.1.4 v2.2.3 v2.3.1; do git checkout --quiet "$tag" docker run --rm -v "$PWD":/src -w /src -e QUALOR_URL -e QUALOR_TOKEN -e QUALOR_PROJECT_KEY \ qualor/scanner:0.15 scan --tag "$tag" done ``` Scan the oldest first, because Qualor orders versions by the date of their scan. ## What a tag scan does A tag scan collects only the dependency list. | | Scan of a branch or merge request | Tag scan | |---|---|---| | Analyzers, metrics, duplication and coverage | run | do not run | | SARIF files and coverage reports | read | not read. The analysis shows the warning `TAG_SCAN_IGNORES_INPUTS` | | The dependency list (Trivy's licence pass) | unless `analyzers.trivy.licenses: false` | always | | Issues, measures and the quality gate | yes | no | | Comments, commit status, webhooks and emails | yes | no | - A tag scan is quick, because no code analyzer runs. - It applies no quality gate. The release's code was already checked on its branch and in merge requests. - It needs Trivy. With `analyzers.trivy.enabled: false`, it exits 2. - When Trivy is not installed, the scan warns `LICENSE_SCAN_FAILED`. A new version then has no packages, and a version scanned before keeps its own. The scanner images include Trivy. - A server older than 0.15 cannot record versions. The scanner then uploads nothing, warns, and exits 0, so the release pipeline does not fail. - With C#, the job still runs `qualor dotnet begin` and your build. `qualor dotnet end` then records the version and reads no Roslyn log. - To run the full scan with the quality gate in a tag pipeline, pass `--branch `. The analysis then belongs to that branch. ## The version label A version's label is `project.version` from `qualor.yml` when it is set. Otherwise it is the tag's name, such as `v2.3.4`. - A label has at most 100 characters. A longer tag needs a shorter `project.version`. Without one, the scanner exits 2 before the upload. - Scanning the same label again replaces that version's packages. A scan without a dependency list leaves them as they are. The version keeps its pin or unsupported mark. - A tag scan that started before the stored tag scan of its label fails with `STALE_ANALYSIS`. The stored packages stay. ## Exit codes | Code | When | |---|---| | 0 | the server recorded the version, and the scanner logged `Recorded version