Dependency list export API

  • Tier: Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Every call to this endpoint requires authentication.

Create a pipeline-level dependency list export

History

Create a new CycloneDX JSON export for all the project dependencies detected in a pipeline.

If an authenticated user does not have permission to read_dependency, this request returns a 403 Forbidden status code.

SBOM exports can be only accessed by the export’s author.

POST /pipelines/:id/dependency_list_exports
AttributeTypeRequiredDescription
idintegeryesThe ID of the pipeline which the authenticated user has access to.
export_typestringyesThis must be set to sbom.
send_emailbooleannoWhen set to true, sends an email notification to the user who requested the export when the export completes.
curl --request POST --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/pipelines/1/dependency_list_exports" --data "export_type=sbom"

The created dependency list export is automatically deleted after 1 hour.

Example response:

{
  "id": 2,
  "has_finished": false,
  "export_type": "sbom",
  "send_email": false,
  "self": "http://gitlab.example.com/api/v4/dependency_list_exports/2",
  "download": "http://gitlab.example.com/api/v4/dependency_list_exports/2/download"
}

Get single dependency list export

Get a single dependency list export.

GET /dependency_list_exports/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the dependency list export.
curl --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/dependency_list_exports/2"

The status code is 202 Accepted when the dependency list export is being generated, and 200 OK when it’s ready.

Example response:

{
  "id": 4,
  "has_finished": true,
  "self": "http://gitlab.example.com/api/v4/dependency_list_exports/4",
  "download": "http://gitlab.example.com/api/v4/dependency_list_exports/4/download"
}

Download dependency list export

Download a single dependency list export.

GET /dependency_list_exports/:id/download
AttributeTypeRequiredDescription
idintegeryesThe ID of the dependency list export.
curl --header "PRIVATE-TOKEN: <private_token>" "https://gitlab.example.com/api/v4/dependency_list_exports/2/download"

The response is 404 Not Found if the dependency list export is not finished yet or was not found.

Example response:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:aec33827-20ae-40d0-ae83-18ee846364d2",
  "version": 1,
  "metadata": {
    "tools": [
      {
        "vendor": "Gitlab",
        "name": "Gemnasium",
        "version": "2.34.0"
      }
    ],
    "authors": [
      {
        "name": "Gitlab",
        "email": "support@gitlab.com"
      }
    ],
    "properties": [
      {
        "name": "gitlab:dependency_scanning:input_file",
        "value": "package-lock.json"
      }
    ]
  },
  "components": [
    {
      "name": "com.fasterxml.jackson.core/jackson-core",
      "purl": "pkg:maven/com.fasterxml.jackson.core/jackson-core@2.9.2",
      "version": "2.9.2",
      "type": "library",
      "licenses": [
        {
          "license": {
            "id": "MIT",
            "url": "https://spdx.org/licenses/MIT.html"
          }
        },
        {
          "license": {
            "id": "BSD-3-Clause",
            "url": "https://spdx.org/licenses/BSD-3-Clause.html"
          }
        }
      ]
    }
  ]
}