GitHub Dependency Graph Gradle Plugin

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

Usage

This plugin is designed to be used in a GitHub Actions workflow, with support coming in a future release of the Gradle Build 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:

import org.gradle.github.GitHubDependencyGraphPlugin
initscript {
  repositories {
    maven {
      url = uri("https://plugins.gradle.org/m2/")
    }
  }
  dependencies {
    classpath("org.gradle:github-dependency-graph-gradle-plugin:+")
  }
}
apply plugin: GitHubDependencyGraphPlugin

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.

Required environment variables

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
• DEPENDENCY_GRAPH_REPORT_DIR (optional): Specifies where the dependency graph report will be generated

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.

Filtering which Gradle Configurations contribute to the dependency graph

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.

To restrict which Gradle subprojects contribute to the report, specify which projects to include via a regular expression. You can provide this value via the DEPENDENCY_GRAPH_INCLUDE_PROJECTS environment variable or system property.

To restrict which Gradle configurations contribute to the report, you can filter configurations by name using a regular expression. You can provide this value via the DEPENDENCY_GRAPH_INCLUDE_CONFIGURATIONS environment variable or system property.

Gradle compatibility

The plugin should be compatible with all versions of Gradle >= 5.0, and has been tested against Gradle versions "5.6.4", "6.9.4", "7.0.2", "7.6.2", "8.0.2" and the current Gradle release.

The plugin is compatible with running Gradle with the configuration-cache enabled. However, this support is limited to Gradle "8.1.0" and later:

• With Gradle "8.0", the build should run successfully, but an empty dependency graph will be generated.
• With Gradle <= "7.6.4", the plugin will cause the build to fail with configuration-cache enabled.

To use this plugin with versions of Gradle older than "8.1.0", you'll need to invoke Gradle with the configuration-cache disabled.

Building/Testing

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

./gradlew check

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

./plugin-self-test-local

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