Configuring automatic dependency submission for your repository

You can use automatic dependency submission to submit transitive dependency data in your repository. This enables you to analyze these transitive dependencies using the dependency graph.

Who can use this feature?

People with admin permissions to a repository, or the security manager role for the repository, can configure automatic dependency submission for that repository.

In this article

About automatic dependency submission

Note

Automatic dependency submission is currently only supported for Maven.

Dependency graph analyzes the manifest and lock files in a repository, in order to help users understand the dependencies that the repository depends on. However, in some ecosystems, the resolution of transitive dependencies occurs at build-time and GitHub isn't able to automatically discover all dependencies based on the contents of the repository alone.

When you enable automatic dependency submission for a repository, GitHub automatically identifies the transitive dependencies in the repository and will submit these dependencies to GitHub using the dependency submission API. You can then report on these dependencies using the dependency graph.

Using automatic dependency submission counts toward your GitHub Actions minutes. For more information, see "About billing for GitHub Actions."

Optionally, you can choose to configure self-hosted runners or GitHub-hosted larger runners for automatic dependency submission. For more information, see "Using self-hosted runners for automatic dependency submission" and "Using GitHub-hosted larger runners for automatic dependency submission."

Prerequisites

Dependency graph must be enabled for the repository for you to enable automatic dependency submission.

You must also enable GitHub Actions for the repository in order to use automatic dependency submission. For more information, see "Managing GitHub Actions settings for a repository."

Enabling automatic dependency submission

Repository administrators can enable or disable automatic dependency submission for a repository by following the steps outlined in this procedure.

Organization owners can enable automatic dependency submission for multiple repositories using a security configuration. For more information, see "Creating a custom security configuration."

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select Enabled.

Once you've enabled automatic dependency submission for a repository, GitHub will:

  • Monitor for changes to the pom.xml file in the root of the repository on all branches of the repository.
  • Perform an automatic dependency submission on each change.

You can view details about the automatic workflows run by viewing the Actions tab of your repository.

Note

Automatic submission will occur on the first push to the pom.xml file after the option is enabled.

Using self-hosted runners for automatic dependency submission

You can configure self-hosted runners to run automatic dependency submission jobs, instead of using the GitHub Actions infrastructure.

  1. Provision one or more self-hosted runners, at the repository or organization level. For more information, see "About self-hosted runners" and "Adding self-hosted runners." The self-hosted runners must be running on Linux or macOS, and must have Docker installed.
  2. Assign a dependency-submission label to each runner you want automatic dependency submission to use. For more information, see "Using labels with self-hosted runners."
  3. In the "Security" section of the sidebar, click Code security and analysis.
  4. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select Enabled for labeled runners.

Once enabled, automatic dependency submission jobs will run on the self-hosted runners, unless:

  • The self-hosted runners are unavailable.
  • There aren't any runner groups tagged with a dependency-submission label.

Note

When using self-hosted runners, you need to add access to the Maven server settings file to allow the dependency submission workflows to connect to private registries. Dependencies from private registries will be included in the dependency tree in the next pom.xml update. For more information about the Maven server settings file, see Security and Deployment Settings in the Maven documentation.

Using GitHub-hosted larger runners for automatic dependency submission

GitHub Team or GitHub Enterprise Cloud users can use larger runners to run automatic dependency submissions jobs.

  1. Provision a larger runner at the organization level with the name dependency-submission. For more information, see "Adding a larger runner to an organization."
  2. Give your repository access to the runner. For more information, see "Allowing repositories to access larger runners."
  3. Under "Dependency graph", click the dropdown menu next to “Automatic dependency submission”, then select Enabled for labeled runners.

Troubleshooting automatic dependency submission

Automatic dependency submission is currently only supported for Maven. The feature uses the Maven Dependency Tree Submission action. For more information, see the documentation for the Maven Dependency Tree Dependency Submission action in the GitHub Marketplace. If your project uses a non-standard Maven configuration, it may not properly generate the dependencies and submit them to the dependency graph.

Further reading