@@ -63,7 +63,7 @@ Here are some details about mandatory and optional permissions used by the templ
Whenever a SBOM file is found, the template uploads it to the Dependency Track server under a certain project.\
The target project is determined by evaluating the `project-path` input / `$DEPTRACK_PROJECT_PATH` variable (see [configuration chapter](#configuration)).
The project path is a sequence of elements separated by forward slashes `/` (although the separator is also configurable with the `path-separator` input / `$DEPTRACK_PATH_SEPARATOR` variable).\
The project path is a sequence of elements separated by double slashes `//` (the separator is also configurable with the `path-separator` input / `$DEPTRACK_PATH_SEPARATOR` variable).\
Each element is expected to be one of the following:
1.`#11111111-1111-1111-1111-111111111111`: a project [Universally Unique Identifier (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier)(starting with a hash `#`)
@@ -81,34 +81,47 @@ Lastly, the project path supports some **expressions**, that will be dynamically
#### Default project path
By default, the Dependency Track project path is set to `$CI_PROJECT_PATH/$CI_PROJECT_NAME-{file_prefix}@{sbom_version}`.
By default, the Dependency Track project path is set to `$CI_PROJECT_NAMESPACE//$CI_PROJECT_PATH-{file_prefix}@$CI_COMMIT_REF_NAME` (with path separator `//`).
That means:
- The project structure in Dependency Track will **match exactly** the GitLab groups, sub-groups and projects hierarchy.
- Each SBOM file found will be uploaded to a sub-project with same name as the project, suffixed with the SBOM file prefix and with project version extracted from the SBOM file.
- If the API key has only the `BOM_UPLOAD` permission, then all the projects hierarchy must pre-exist down to the parent project and even SBOM sub-projects.
- If the API key has the extra `PROJECT_CREATION_UPLOAD` permission, then all the projects hierarchy must pre-exist down to the parent project (hosting the SBOM sub-projects).
- If the API key has the extra `VIEW_PORTFOLIO` and `PORTFOLIO_MANAGEMENT` permissions (not recommanded), then the project hierarchy will be automatically created by the template if it doesn't exist.
- The project structure in Dependency Track will always be two levels deep:
- a _root_ project bearing the name of the GitLab project namespace,
- and _leaf_ projects (hosting SBOM files) bearing the full path of the GitLab project as a name, suffixed with the
SBOM file prefix and with project version matching either the Git branch name or the Git tag name (depending on the
kind of pipeline that originated the SBOM file).
- If the API key has only the `BOM_UPLOAD` permission, then all the projects hierarchy must pre-exist down to the leaf
sub-projects.
- If the API key has the extra `PROJECT_CREATION_UPLOAD` permission, then only the root project must pre-exist, the template
will automatically create the leaf projects if not found.
- If the API key has the extra `VIEW_PORTFOLIO` and `PORTFOLIO_MANAGEMENT` permissions (not recommanded), then the entire
project hierarchy will be automatically created by the template if it doesn't exist.
Example: Let's imagine a GitLab project located in `acme-program/acme-services/acme-user-api` with 2 SBOM files generated by the pipeline:
-`py-sbom.cyclonedx.json`: the SBOM of the Python application implementation, with version `1.1.0`
-`docker-sbom.cyclonedx.json`: the SBOM of the container image, with version `main`
Lastly, let's suppose the project production branch is `main`, and 2 software versions have been released so far: `1.0.0` and `1.1.0`.
Then the corresponding Dependency Track project structure will be:
> :bulb: this default configuration handles the Dependency Track constraint that each project name has to be globally
> unique in the server.
#### Other use cases
The default template behavior can be changed by overridding the `project-path` input / `$DEPTRACK_PROJECT_PATH` variable.
@@ -126,17 +139,6 @@ Examples:
-`acme-program@v2/acme-services@v1.3/acme-user-api@v1.3/acme-user-api-{file_prefix}`: complete project path only defined by project names and versions<br/>
:information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project and its ancestors if they don't exist
> :bulb: you may decide to overwrite the path separator (ex: double slash `//`) if you want your project names to contain slashes.
>
> Example:
>
> ```yaml
> variables:
> DEPTRACK_PATH_SEPARATOR: "//"
> # flaten the projects hierarchy to depth 2 (full GitLab project namespace is mapped to one single DT project)
