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.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.github.com/repos///dependency-graph/snapshots' \
--header 'Content-Type: application/json' \
--data-raw '{
    "detector": {
        "name": "docker buildtime detector",
        "url": "http://example.com/docker-buildtimer-detector",
        "version": "1.0.0"
    },
    "job": {
        "correlator": "yourworkflowname_yourjobname",
        "html_url": "http://example.com/build",
        "id": "5622a2b0-63f6-4732-8c34-a1ab27e102a11"
    },
    "manifests": {
        "property1": {
            "file": {
                "source_location": "/src/build/package-lock.json"
            },
            "metadata": {
                "property1": "string",
                "property2": "string"
            },
            "name": "package-lock.json",
            "resolved": {
                "property1": {
                    "dependencies": "@actions/http-client",
                    "metadata": {
                        "property1": "string",
                        "property2": "string"
                    },
                    "package_url": "pkg:/npm/%40actions/http-client@1.0.11",
                    "relationship": "direct",
                    "scope": "runtime"
                },
                "property2": {
                    "dependencies": "@actions/http-client",
                    "metadata": {
                        "property1": "string",
                        "property2": "string"
                    },
                    "package_url": "pkg:/npm/%40actions/http-client@1.0.11",
                    "relationship": "direct",
                    "scope": "runtime"
                }
            }
        },
        "property2": {
            "file": {
                "source_location": "/src/build/package-lock.json"
            },
            "metadata": {
                "property1": "string",
                "property2": "string"
            },
            "name": "package-lock.json",
            "resolved": {
                "property1": {
                    "dependencies": "@actions/http-client",
                    "metadata": {
                        "property1": "string",
                        "property2": "string"
                    },
                    "package_url": "pkg:/npm/%40actions/http-client@1.0.11",
                    "relationship": "direct",
                    "scope": "runtime"
                },
                "property2": {
                    "dependencies": "@actions/http-client",
                    "metadata": {
                        "property1": "string",
                        "property2": "string"
                    },
                    "package_url": "pkg:/npm/%40actions/http-client@1.0.11",
                    "relationship": "direct",
                    "scope": "runtime"
                }
            }
        }
    },
    "metadata": {
        "property1": "string",
        "property2": "string"
    },
    "ref": "refs/heads/main",
    "scanned": "2020-06-13T19:52:50.000Z",
    "sha": "ddc951f4b1293222421f2c8df679786153acf689",
    "version": 0
}'

Response Example

{
    "created_at": "string",
    "id": 0,
    "message": "string",
    "result": "string"
}

Request

Path Params

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.

Body Params application/json

Create a new snapshot of a repository's dependencies.

detector

object

required

A description of the detector used.

name

string

required

The name of the detector used.

Example:

docker buildtime detector

url

string

required

The url of the detector used.

Example:

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

version

string

required

The version of the detector used.

Example:

1.0.0

job

object

required

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

optional

The url for the job.

Example:

http://example.com/build

string

required

The external ID of the job.

Example:

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

manifests

object

optional

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

Additional properties

object (manifest)

optional

metadata

object (metadata)

optional

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

ref

string

required

The repository branch that triggered this snapshot.

Example:

refs/heads/main

Match pattern:

^refs/

scanned

string <date-time>

required

The time at which the snapshot was scanned.

Example:

2020-06-13T19:52:50.000Z

sha

string

required

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

>= 40 characters<= 40 characters

Example:

ddc951f4b1293222421f2c8df679786153acf689

version

integer

required

The version of the repository snapshot submission.

Examples

Responses

🟢201Response

application/json

Body

created_at

string

required

The time at which the snapshot was created.

integer

required

ID of the created snapshot.

message

string

required

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

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.

Modified at 2023-08-15 02:59:24

Get a diff of the dependencies between commits