Configuring automatic dependency submission for your repository

About automatic dependency submission

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.

   

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.

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.

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.

Automatic dependency submission makes a best effort to cache package downloads between runs using the Cache action to speed up workflows. For self-hosted runners, you may want to manage this cache within your own infrastructure. To do this, you can disable the built-in caching by setting an environment variable of GH_DEPENDENCY_SUBMISSION_SKIP_CACHE to true. For more information, see "Store information in variables."

Further reading

• "About supply chain security"
• "Using the dependency submission API"