A Gradle plugin for generating a GitHub dependency graph for a Gradle build, which can be uploaded to the GitHub Dependency Submission API.

This plugin is designed to be used in a GitHub Actions workflow, and is tightly integrated into the gradle/actions/dependency-submission action.

For other uses, the core plugin (org.gradle.github.GitHubDependencyGraphPlugin) should be applied to the Gradle instance via a Gradle init script as follows:

This causes 2 separate plugins to be applied, that can be used independently:

• GitHubDependencyExtractorPlugin collects all dependencies that are resolved during a build execution and writes these to a file. The output file can be found at <root>/build/reports/github-depenency-graph-snapshots/<job-correlator>.json.
• ForceDependencyResolutionPlugin creates a ForceDependencyResolutionPlugin_resolveAllDependencies task that will attempt to resolve all dependencies for a Gradle build, by simply invoking dependencies on all projects.

The following environment variables configure the snapshot generated by the GitHubDependencyExtractorPlugin. See the GitHub Dependency Submission API docs for details:

• GITHUB_DEPENDENCY_GRAPH_JOB_CORRELATOR: Sets the job.correlator value for the dependency submission
• GITHUB_DEPENDENCY_GRAPH_JOB_ID: Sets the job.id value for the dependency submission
• GITHUB_DEPENDENCY_GRAPH_REF: Sets the ref value for the commit that generated the dependency graph
• GITHUB_DEPENDENCY_GRAPH_SHA: Sets the sha value for the commit that generated the dependency graph
• GITHUB_DEPENDENCY_GRAPH_WORKSPACE: Sets the root directory of the github repository. Must be an absolute path.
• DEPENDENCY_GRAPH_REPORT_DIR (optional): Specifies where the dependency graph report will be generated. Must be an absolute path.

• GITHUB_DEPENDENCY_GRAPH_DETECTOR_NAME: Sets the detector.name value for the dependency submission. Defaults to GitHub Dependency Graph Gradle Plugin
• GITHUB_DEPENDENCY_GRAPH_DETECTOR_VERSION: Sets the detector.version value for the dependency submission. Defaults to current version of the plugin.
• GITHUB_DEPENDENCY_GRAPH_DETECTOR_URL: Sets the detector.url value for the dependency submission. Defaults to https://github.com/gradle/github-dependency-graph-gradle-plugin

Each of these values can also be provided via a system property. eg: Env var DEPENDENCY_GRAPH_REPORT_DIR can be set with -DDEPENDENCY_GRAPH_REPORT_DIR=... on the command-line.

If you do not want to include every dependency configuration in every project in your build, you can limit the dependency extraction to a subset of these.

The following parameters control the set of projects and configurations that contribute dependencies. Each of these is a regular expression value, and can set either as an environment variable or as a system property on the command line.

The GitHub dependency graph allows a scope to be assigned to each reported dependency. The only permissible values for scope are 'runtime' and 'development'.

The following parameters control the set of projects and configurations that provide 'runtime' scoped dependencies. Any dependency resolution that does not match these parameters will be scoped 'development'.

Each of these parameters is a regular expression value, and can set either as an environment variable or as a system property on the command line.

By default, no scope is assigned to dependencies in the graph. To enable scopes in the generated dependency graph, at least one of these parameters must be configured.

For dependencies that are resolved in multiple projects and/or multiple configurations, only a single 'runtime' scoped resolution is required for that dependency to be scoped 'runtime'.

The plugin is compatible with most versions of Gradle >= 5.2, and all changes are tested against a range of versions.

The plugin is compatible with running Gradle with the configuration-cache enabled: this support is limited to Gradle "8.1.0" and later. Earlier Gradle versions will not work with --configuration-cache. Note that no dependency graph will be generated when configuration state is loaded from the configuration-cache.

When using this plugin with dependency signature verification enabled, the you should be able to update your dependency-verification.xml file using --write-verification-metadata pgp,sha256.

However, if this doesn't work, you can add the following to your dependency-verificaton.xml file:

As well as the GitHubDependencyGraphPlugin, which is tailored for use by the gradle/actions/dependency-submission GitHub Action, this repository also provides the SimpleDependencyGraphPlugin, which generates dependency-graph outputs in simple text format.

To use the SimpleDependencyGraphPlugin you'll need to create an init.gradle file to apply the plugin to your project:

and then execute the task to resolve all dependencies in your project:

You'll find the generated files in build/reports/dependency-graph-snapshots.

After generating the dependency reports as described, it is possible to determine the dependency source by:

1. Locate the dependency (including matching version) in the dependency-resolution.json file.
2. Inspect each resolvedBy entry for the path and configuration values. The scope value is unimportant in this context.
3. Use the built-in dependencyInsight task to determine exactly how the dependency was resolved. The path indicates the project where the task should be executed, and the configuration is an input to the task.

For example, given the following from the dependency-resolution.json report:

You would run the command:

If the configuration value in dependency-resolution.json is "classpath", or for some other reason the above instructions do not work, it is possible to recostruct the full resolution path using the generated dependency-graph.json file.

Search for the exact dependency version in dependency-graph.json, and you'll see an "id" entry for that dependency as well as one or more "dependencies" entries. By tracing back through the dependencies you can determine the underlying source of the dependency.

To build and test this plugin, run the following task:

To self-test this plugin and generate a dependency graph for this repository, run:

The generated dependency graph will be submitted to GitHub only if you supply a GitHub API token via the environment variable GITHUB_TOKEN.