Creating a more comprehensive dependency graph with build time detection

Understanding your dependencies is fundamental to good security practices. GitHub’s dependency graph detects your project’s dependencies and allows us to send Dependabot alerts when vulnerabilities are found in them.

Until now, GitHub built the dependency graph entirely from static scans of checked-in manifest files. That limited the completeness of the graph in some ecosystems. Today, we’re releasing an API that allows you to upload dependency information directly to GitHub, for instance, from your build tool. By combining build time detection with static scanning, GitHub can provide a more comprehensive dependency graph, alert you of more vulnerabilities, and in the future offer broader ecosystem support.

Going beyond alerts for statically analyzed dependencies

Dependency graph has traditionally supported package managers where the dependencies can be statically parsed from a manifest or lockfile. Not all package managers work like this. Some pull in additional dependencies when the software is built, and others have dependency declarations that GitHub can’t currently scan for statically. The submission API complements dependency graph’s existing static scanning to offer support for these kinds of package managers.

Getting the full picture of dependency scans

The dependency graph only gets a partial picture of your project’s dependencies if you’re using a package manager, like Maven, where direct dependencies are defined in the pom.xml, but transitive dependencies are not. When you don’t know what you rely on transitively, you can open yourself up to risk through any vulnerabilities that are brought in with them.

Making dependency scans possible for new package managers

For other package managers, like Gradle and sbt, dependencies cannot reliably be parsed statically. Dependencies are determined at build time, and they can change depending on the build environment itself or non-pinned dependencies resolving different versions at different times. With the submission API, you can include steps in your CI workflow to submit the dependencies for your latest build to GitHub’s dependency graph.

Submitting your dependencies to GitHub

The GitHub dependency submission API accepts a simple list of dependencies that reflect the current state of your repository in a commit. A typical flow will be to add a GitHub Action that supports the dependency submission API to your repository. We’re launching the API with a supporting action for Go, which adds support for transitive dependency detection and gives a more accurate picture of your Go dependencies, and we’re working with the community to create actions that support additional package managers and tools. Keep an eye on our blog for more information on third-party integrations!

You can also build your own action or submit dependencies directly to the API. Submissions are associated with a commit SHA and need to be made in the required format. The Dependency Submission Toolkit helps with the conversion and submission, and can be used to make a GitHub Action for your desired package manager. Building your own submission workflow gives you the flexibility to address any complexities within your repository setup, and with the same powerful end result: a more comprehensive dependency graph!

Viewing submitted dependencies in your dependency graph

The dependency graph will show the most recent set of dependencies submitted to your repository’s default branch. If your repository has more than one workflow submitting dependencies for different package managers, then the latest submissions for each one will be included in your dependency graph.

Help us improve the dependency submission API

The dependency submission API is an early beta. We are working hard to improve the experience for submitting, retrieving, and viewing dependencies and will be shipping new updates to improve the overall functionality. Improvements to come include viewing metadata for submitted dependencies and accessing historical submissions, as well as surfacing submitted dependencies in dependency graph scenarios, like dependency review and dependency insights.

As we improve, we are eager to hear your feedback to make it even better! Let us know how you use the dependency submission API and how you’d like it to evolve. Whether you’re using ready-made actions or building your own submission workflow, you can leave any and all feedback using GitHub Discussions.

Start using the GitHub dependency submission API

To learn more about using the dependency submission API, check out our documentation to get started, or use the Dependency Submission Toolkit to write your own detector!

Written by

Courtney Claessens

@courtneycl