Note:
The ability to use the REST API for dependency submission is currently in public beta and subject to change.
You can use the REST API to submit dependencies for a project. This enables you to add dependencies, such as those resolved when software is compiled or built, to GitHub's dependency graph feature, providing a more complete picture of all of your project's dependencies.
The dependency graph shows any dependencies you submit using the API in addition to any dependencies that are identified from manifest or lock files in the repository (for example, a
package-lock.json
file in a JavaScript project). For more information about viewing the dependency graph, see "
Exploring the dependencies of a repository
."
Submitted dependencies will receive Dependabot alerts and Dependabot security updates for any known vulnerabilities. You will only get Dependabot alerts for dependencies that are from one of the supported ecosystems for the GitHub Advisory Database. For more information about these ecosystems, see "
About the GitHub Advisory database
." For transitive dependencies submitted via the dependency submission API, Dependabot will automatically open pull requests to update the parent dependency, if an update is available.
Submitted dependencies will be shown in dependency review, but are
not
available in your organization's dependency insights.
Note:
The dependency review API and the dependency submission API work together. This means that the dependency review API will include dependencies submitted via the dependency submission API. This feature is currently in public beta and subject to change.
Dependencies are submitted to the dependency submission API in the form of a snapshot. A snapshot is a set of dependencies associated with a commit SHA and other metadata, that reflects the current state of your repository for a commit. Snapshots can be generated from your dependencies detected at build time or from a software bill of materials (SBOM). There are GitHub Actions that support either of these use cases. For more information about the dependency submission API, see "
REST API endpoints for dependency submission
."
You can use the dependency submission API in a GitHub Actions workflow to submit dependencies for your project when your project is built.
The simplest way to use the dependency submission API is by adding a pre-made action to your repository that will gather and convert the list of dependencies to the required snapshot format and submit the list to the API. Actions that complete these steps for various ecosystems are available on GitHub Marketplace. Some of these actions are provided by third parties. You can find links to the currently available actions in the table below.
Note:
For the Component Detection dependency submission action, other supported ecosystems include Vcpkg, Conan, Conda, Crates, as well as NuGet.
For example, the following
Go Dependency Submission
workflow calculates the dependencies for a Go build-target (a Go file with a
main
function) and submits the list to the dependency submission API.
name:
Go
Dependency
Submission
on:
push:
branches:
-
main
permissions:
contents:
write
env:
GOPROXY:
''
GOPRIVATE:
''
jobs:
go-action-detection:
runs-on:
ubuntu-latest
steps:
-
name:
'Checkout Repository'
uses:
actions/checkout@v4
-
uses:
actions/setup-go@v5
with:
go-version:
">=1.18.0"
-
name:
Run
snapshot
action
uses:
actions/go-dependency-submission@v1
with:
go-mod-path:
go-example/go.mod
go-build-target:
go-example/cmd/octocat.go
Alternatively, you can write your own action to submit dependencies for your project at build-time. Your workflow should:
- Generate a list of dependencies for your project.
- Translate the list of dependencies into the snapshot format accepted by the dependency submission API. For more information about the format, see the body parameters for the "Create a repository snapshot" API endpoint in "
REST API endpoints for dependency submission
."
- Submit the formatted list of dependencies to the dependency submission API.
GitHub Enterprise Cloud maintains the
Dependency Submission Toolkit
, a TypeScript library to help you build your own GitHub Action for submitting dependencies to the dependency submission API. For more information about writing an action, see "
Creating actions
".
An SBOM is a formal, machine-readable inventory of a project's dependencies and associated information (such as versions, package identifiers, and licenses). SBOMs help reduced supply chain risks by:
- providing transparency about the dependencies used by your repository
- allowing vulnerabilities to be identified early in the process
- providing insights in the license compliance, security, or quality issues that may exist in your codebase
- enabling you to better comply with various data protection standards
To generate an SBOM, you can use:
To receive Dependabot alerts for dependencies that have known vulnerabilities, you can upload and submit the SBOM to the dependency submission API. To submit an SBOM to the dependency submission API, you can use one of the actions in the following table.
For example, the following
SPDX Dependency Submission Action
workflow calculates the dependencies for a repository, generates an exportable SBOM in SPDX 2.2 format, and submits it to the dependency submission API.
name:
SBOM
upload
on:
workflow_dispatch:
push:
branches:
[
"main"
]
jobs:
SBOM-upload:
runs-on:
ubuntu-latest
permissions:
id-token:
write
contents:
write
steps:
-
uses:
actions/checkout@v4
-
name:
Generate
SBOM
run:
|
curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
chmod +x $RUNNER_TEMP/sbom-tool
$RUNNER_TEMP/sbom-tool generate -b . -bc . -pn $ -pv 1.0.0 -ps OwnerName -nsb https://sbom.mycompany.com -V Verbose
-
uses:
actions/upload-artifact@v4
with:
name:
sbom
path:
_manifest/spdx_2.2
-
name:
SBOM
upload
uses:
advanced-security/spdx-dependency-submission-action@v0.0.1
with:
filePath:
"_manifest/spdx_2.2/"