Dependency Graph

Download Spec

Endpoints to access Dependency Graph features.

Get a diff of the dependencies between commits

get /repos/{owner}/{repo}/dependency-graph/compare/{basehead}

Gets the diff of the dependency changes between two commits of a repository, based on the changes to the dependency manifests made in those commits.

owner

string

required

The account owner of the repository. The name is not case sensitive.

repo

string

required

The name of the repository. The name is not case sensitive.

basehead

string

required

The base and head Git revisions to compare. The Git revisions will be resolved to commit SHAs. Named revisions will be resolved to their corresponding HEAD commits, and an appropriate merge base will be determined. This parameter expects the format {base}...{head}.

name

string

The full path, relative to the repository root, of the dependency manifest file.

Response

Examples Schema

Response

[
  {
    "change_type": "removed",
    "manifest": "package.json",
    "ecosystem": "npm",
    "name": "helmet",
    "version": "4.6.0",
    "package_url": "pkg:npm/helmet@4.6.0",
    "license": "MIT",
    "source_repository_url": "https://github.com/helmetjs/helmet",
    "vulnerabilities": []
  },
  {
    "change_type": "added",
    "manifest": "package.json",
    "ecosystem": "npm",
    "name": "helmet",
    "version": "5.0.0",
    "package_url": "pkg:npm/helmet@5.0.0",
    "license": "MIT",
    "source_repository_url": "https://github.com/helmetjs/helmet",
    "vulnerabilities": []
  },
  {
    "change_type": "added",
    "manifest": "Gemfile",
    "ecosystem": "rubygems",
    "name": "ruby-openid",
    "version": "2.7.0",
    "package_url": "pkg:gem/ruby-openid@2.7.0",
    "license": null,
    "source_repository_url": "https://github.com/openid/ruby-openid",
    "vulnerabilities": [
      {
        "severity": "critical",
        "advisory_ghsa_id": "GHSA-fqfj-cmh6-hj49",
        "advisory_summary": "Ruby OpenID",
        "advisory_url": "https://github.com/advisories/GHSA-fqfj-cmh6-hj49"
      }
    ]
  }
]

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Dependency Graph Diff

array[object]

A diff of the dependencies between two commits.

object

change_type

string

required

Enum
  • added
  • removed

manifest

string

required

Example
"path/to/package-lock.json"

ecosystem

string

required

Example
"npm"

name

string

required

Example
"@actions/core"

version

string

required

Example
"1.0.0"

package_url

string or null

required

Example
"pkg:/npm/%40actions/core@1.1.0"

license

string or null

required

Example
"MIT"

source_repository_url

string or null

required

Example
"https://github.com/github/actions"

vulnerabilities

array[object]

required

object

severity

string

required

Example
"critical"

advisory_ghsa_id

string

required

Example
"GHSA-rf4j-j272-fj86"

advisory_summary

string

required

Example
"A summary of the advisory."

advisory_url

string

required

Example
"https://github.com/advisories/GHSA-rf4j-j272-fj86"

scope

string

required

Where the dependency is utilized. development means that the dependency is only utilized in the development environment. runtime means that the dependency is utilized at runtime and in the development environment.

Enum
  • unknown
  • runtime
  • development

Link

string

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

Export a software bill of materials (SBOM) for a repository.

get /repos/{owner}/{repo}/dependency-graph/sbom

Exports the software bill of materials (SBOM) for a repository in SPDX JSON format.

owner

string

required

The account owner of the repository. The name is not case sensitive.

repo

string

required

The name of the repository. The name is not case sensitive.

Response

Examples Schema

Response

{
  "sbom": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "spdxVersion": "SPDX-2.3",
    "creationInfo": {
      "created": "2021-09-01T00:00:00Z",
      "creators": [
        "Tool: GitHub.com-Dependency-Graph"
      ]
    },
    "name": "github/example",
    "dataLicense": "CC0-1.0",
    "documentDescribes": [
      "github/example"
    ],
    "documentNamespace": "https://github.com/github/example/dependency_graph/sbom-abcdef123456",
    "packages": [
      {
        "SPDXID": "SPDXRef-Package",
        "name": "rubygems:rails",
        "versionInfo": "1.0.0",
        "downloadLocation": "NOASSERTION",
        "filesAnalyzed": false,
        "licenseConcluded": "NOASSERTION",
        "licenseDeclared": "NOASSERTION"
      }
    ]
  }
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

sbom

object (sbom)

required

SPDXID

string

required

The SPDX identifier for the SPDX document.

Example
"SPDXRef-DOCUMENT"

spdxVersion

string

required

The version of the SPDX specification that this document conforms to.

Example
"SPDX-2.3"

creationInfo

object (creationInfo)

required

created

string

required

The date and time the SPDX document was created.

Example
"2021-11-03T00:00:00Z"

creators

array[string]

required

The tools that were used to generate the SPDX document.

string

Example
"GitHub"

name

string

required

The name of the SPDX document.

Example
"github/github"

dataLicense

string

required

The license under which the SPDX document is licensed.

Example
"CC0-1.0"

documentDescribes

array[string]

required

The name of the repository that the SPDX document describes.

string

Example
"github/github"

documentNamespace

string

required

The namespace for the SPDX document.

Example
"https://github.com/example/dependency_graph/sbom-123"

packages

array[object]

required

object

SPDXID

string

A unique SPDX identifier for the package.

Example
"SPDXRef-Package"

name

string

The name of the package.

Example
"rubygems:github/github"

versionInfo

string

The version of the package. If the package does not have an exact version specified, a version range is given.

Example
"1.0.0"

downloadLocation

string

The location where the package can be downloaded, or NOASSERTION if this has not been determined.

Example
"NOASSERTION"

filesAnalyzed

boolean

Whether the package's file content has been subjected to analysis during the creation of the SPDX document.

Example
false

licenseConcluded

string

The license of the package as determined while creating the SPDX document.

Example
"MIT"

licenseDeclared

string

The license of the package as declared by its author, or NOASSERTION if this information was not available when the SPDX document was created.

Example
"NOASSERTION"

supplier

string

The distribution source of this package, or NOASSERTION if this was not determined.

Example
"NOASSERTION"

externalRefs

array[object]

object

referenceCategory

string

required

The category of reference to an external resource this reference refers to.

Example
"PACKAGE-MANAGER"

referenceLocator

string

required

A locator for the particular external resource this reference refers to.

Example
"pkg:gem/rails@6.0.1"

referenceType

string

required

The category of reference to an external resource this reference refers to.

Example
"purl"

Link

string

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

Create a snapshot of dependencies for a repository

post /repos/{owner}/{repo}/dependency-graph/snapshots

Create a new snapshot of a repository's dependencies. You must authenticate using an access token with the repo scope to use this endpoint for a repository that the requesting user has access to.

owner

string

required

The account owner of the repository. The name is not case sensitive.

repo

string

required

The name of the repository. The name is not case sensitive.

version

int

required

The version of the repository snapshot submission.

job

object (job)

required

id

string

required

The external ID of the job.

Example
"5622a2b0-63f6-4732-8c34-a1ab27e102a11"

correlator

string

required

Correlator provides a key that is used to group snapshots submitted over time. Only the "latest" submitted snapshot for a given combination of job.correlator and detector.name will be considered when calculating a repository's current dependencies. Correlator should be as unique as it takes to distinguish all detection runs for a given "wave" of CI workflow you run. If you're using GitHub Actions, a good default value for this could be the environment variables GITHUB_WORKFLOW and GITHUB_JOB concatenated together. If you're using a build matrix, then you'll also need to add additional key(s) to distinguish between each submission inside a matrix variation.

Example
"yourworkflowname_yourjobname"

html_url

string

The url for the job.

Example
"http://example.com/build"

sha

string

required

The commit SHA associated with this dependency snapshot. Maximum length: 40 characters.

Min Length
40
Max Length
40
Example
"ddc951f4b1293222421f2c8df679786153acf689"

ref

string

^refs/

required

The repository branch that triggered this snapshot.

Example
"refs/heads/main"

detector

object (detector)

required

A description of the detector used.

name

string

required

The name of the detector used.

Example
"docker buildtime detector"

version

string

required

The version of the detector used.

Example
"1.0.0"

url

string

required

The url of the detector used.

Example
"http://example.com/docker-buildtimer-detector"

metadata

object (metadata)

User-defined metadata to store domain-specific information limited to 8 keys with scalar values.

manifests

object (manifests)

A collection of package manifests, which are a collection of related dependencies declared in a file or representing a logical group of dependencies.

scanned

string

date-time

required

The time at which the snapshot was scanned.

Example
"2020-06-13T14:52:50-05:00"

Request

{
  "version": 0,
  "sha": "ce587453ced02b1526dfb4cb910479d431683101",
  "ref": "refs/heads/main",
  "job": {
    "correlator": "yourworkflowname_youractionname",
    "id": "yourrunid"
  },
  "detector": {
    "name": "octo-detector",
    "version": "0.0.1",
    "url": "https://github.com/octo-org/octo-repo"
  },
  "scanned": "2022-06-14T20:25:00Z",
  "manifests": {
    "package-lock.json": {
      "name": "package-lock.json",
      "file": {
        "source_location": "src/package-lock.json"
      },
      "resolved": {
        "@actions/core": {
          "package_url": "pkg:/npm/%40actions/core@1.1.9",
          "dependencies": [
            "@actions/http-client"
          ]
        },
        "@actions/http-client": {
          "package_url": "pkg:/npm/%40actions/http-client@1.0.7",
          "dependencies": [
            "tunnel"
          ]
        },
        "tunnel": {
          "package_url": "pkg:/npm/tunnel@0.0.6"
        }
      }
    }
  }
}

Response

Examples Schema

Response

{
  "id": 12345,
  "created_at": "2018-05-04T01:14:52Z",
  "message": "Dependency results for the repo have been successfully updated.",
  "result": "SUCCESS"
}

id

int

required

ID of the created snapshot.

created_at

string

required

The time at which the snapshot was created.

result

string

required

Either "SUCCESS", "ACCEPTED", or "INVALID". "SUCCESS" indicates that the snapshot was successfully created and the repository's dependencies were updated. "ACCEPTED" indicates that the snapshot was successfully created, but the repository's dependencies were not updated. "INVALID" indicates that the snapshot was malformed.

message

string

required

A message providing further details about the result, such as why the dependencies were not updated.

Was this page helpful?