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.

谁可以使用此功能？

具有管理员角色的存储库所有者、组织所有者、安全管理员和用户

本文内容

About automatic dependency submission

注意

Automatic dependency submission does not support all package ecosystems. For the current list of supported ecosystems, see 依赖项关系图支持的包生态系统.

Dependency graph analyzes the manifest and lock files in a repository, in order to help users understand the upstream packages that their software project 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 依赖项提交 API. You can then explore these dependencies using the dependency graph. Dependabot will notify you about security updates for these dependencies by generating Dependabot alerts .

Using automatic dependency submission counts toward your GitHub Actions minutes. For more information, see GitHub Actions 计费.

Optionally, you can choose to configure self-hosted runners or GitHub-hosted 大型运行器 for automatic dependency submission. For more information, see Accessing private registries with self-hosted runners 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 管理存储库的 GitHub Actions 设置.

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 删除自定义安全配置.

  1. 在 GitHub 上，导航到存储库的主页面。

  2. 在仓库名称下，单击 “Settings”****。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Security”部分中，单击“ Advanced Security”****。

  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:

  • Watch for pushes to the repository.
  • Run the dependency graph build action associated with the package ecosystem for any manifests in the repository.
  • Perform an automatic dependency submission with the results.

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

注意

After you enable automatic dependency submission, we'll automatically trigger a run of the action. Once enabled, it'll run each time a commit to the default branch updates a manifest.

Accessing private registries with self-hosted runners

You can configure self-hosted runners to run automatic dependency submission jobs, instead of using the GitHub Actions infrastructure. This is necessary to access private Maven registries. The self-hosted runners must be running on Linux or macOS. For .NET and Python auto-submission, they must have access to the public internet in order to download the latest component-detection release.

  1. Provision one or more self-hosted runners, at the repository or organization level. For more information, see 自托管运行程序 and 添加自托管的运行器.
  2. Assign a dependency-submission label to each runner you want automatic dependency submission to use. For more information, see 将标签与自托管运行程序结合使用.
  3. 在边栏的“Security”部分中，单击“ Advanced Security”****。
  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.

注意

For Maven or Gradle projects that use self-hosted runners with private Maven registries, you need to modify the Maven server settings file to allow the dependency submission workflows to connect to the registries. For more information about the Maven server settings file, see Security and Deployment Settings in the Maven documentation.

Configuring network access for self-hosted runners

If your self-hosted runners operate behind a firewall with restricted outbound internet access, you must add certain URLs to the allowlist for automatic dependency submission. The required URLs depend on the ecosystems your repositories use.

Required URLs for all ecosystems

These URLs are required for all automatic dependency submission workflows:

  • https://github.com—Required for accessing GitHub and downloading actions.
  • https://api.github.com—Required for GitHub API access.
  • https://*.githubusercontent.com—Required for downloading action source code and releases (including raw.githubusercontent.com, github-releases.githubusercontent.com, and objects.githubusercontent.com).

Ecosystem-specific URLs

Depending on the ecosystems you use, you may need to allowlist additional URLs.

Go
  • https://go.dev—For downloading the Go toolchain.
  • https://golang.org—Alternate domain for Go downloads.
  • https://proxy.golang.org—Official Go module proxy for downloading Go modules during dependency detection.

注意

The actions/go-versions repository is accessed via https://raw.githubusercontent.com, which is already covered in the general requirements.

Java (Maven and Gradle)
  • https://repo.maven.apache.org—Maven Central repository for downloading dependencies.
  • https://api.adoptium.net—For downloading Adoptium/Temurin JDK distributions (default distribution used by actions/setup-java).

If you use a different JDK distribution, you may also need:

  • https://aka.ms and https://download.microsoft.com—For Microsoft Build of OpenJDK (note: aka.ms is also used for .NET downloads).
  • https://download.oracle.com—For Oracle JDK.
  • https://api.azul.com—For Azul Zulu OpenJDK.
.NET (C#, F#, Visual Basic)
  • https://aka.ms—Microsoft URL shortener that redirects to .NET download locations.
  • https://builds.dotnet.microsoft.com—Primary feed for .NET SDK and runtime downloads.
  • https://ci.dot.net—Secondary feed for .NET builds.

注意

The microsoft/component-detection tool used by .NET autosubmission is downloaded from GitHub releases, which is already covered in the general requirements (https://github.com and https://*.githubusercontent.com).

Python
  • https://python.org—For downloading Python interpreters.

注意

The actions/python-versions repository and microsoft/component-detection releases are accessed via URLs already covered in the general requirements (https://*.githubusercontent.com and https://github.com).

Using GitHub-hosted 大型运行器 for automatic dependency submission

GitHub Team or GitHub Enterprise Cloud users can use 大型运行器 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 大型运行器 to an organization.
  2. Give your repository access to the runner. For more information, see Allowing repositories to access 大型运行器.
  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 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 在变量中存储信息.

Manifest deduplication

依赖项关系图可以通过三种不同的方式来了解依赖项：静态分析、自动提交和手动提交。 一个仓库可以配置多种方法，这会导致同一个包清单被扫描多次，而且每次扫描可能会产生不同的结果。 依赖项关系图使用去重逻辑来分析输出，为每个清单文件优先选取最准确的信息。

依赖项关系图会依据以下优先级规则，仅显示每个清单文件的一个实例。

  1. 用户提交具有最高优先级，因为它们通常是在项目构建期间创建的，包含最完整的信息。****
    • 如果存在来自不同检测器的多个手动快照，这些快照将根据关联器按字母顺序进行排序，并且会采用第一个快照。
    • 如果有两个使用相同检测器的关联器，已解析的依赖项将合并。 有关关联器和检测器的详细信息，请参阅 适用于依赖项提交的 REST API 终结点。
  2. 自动提交具有第二高的优先级，因为它们同样是在项目构建期间创建的，但并非由用户提交。****
  3. 静态分析结果会在没有其他可用数据的情况下被采用。****

Package ecosystem-specific information

Maven projects

For Maven projects, automatic dependency submission runs an open source fork of the Maven Dependency Tree Dependency Submission. The fork allows GitHub to stay in sync with the upstream repository plus maintain some changes that are only applicable to automatic submission. The fork's source is available at advanced-security/maven-dependency-submission-action.

If your repository's dependencies seem inaccurate, check that the timestamp of the last dependency graph build matches the last change to your pom.xml file. The timestamp is visible on the table of alerts in the repository's Dependabot alerts tab. Pushing a commit which updates pom.xml will trigger a new run of the Dependency Tree Submission action and force a rebuild of that repository's dependency graph.

Gradle projects

For Gradle projects, automatic dependency submission runs a fork of the open source Gradle actions from gradle/actions. The fork is available at actions/gradle-build-tools-actions. You can view the results of the autosubmission action under your repository's Actions tab. Each run will be labeled "Automatic Dependency Submission (Gradle)" and its output will contain the JSON payload which the action submitted to the API.

.NET projects

The .NET autosubmission action uses the open source component-detection project as the engine for its dependency detection. It supports .NET 8.x, 9.x, and 10.x. .NET autosubmission runs if the repository's dependabot.yml defines nuget as a package-ecosystem or when there is a supported manifest file in the root directory of the repository. Supported manifest files include .sln, .csproj, packages.config, .vbproj, .vcxproj, and .fsproj.

Python projects

Python uses the open source component-detection project as its underlying graph generation engine. The autosubmission action for Python will only run if there is a requirements.txt file in the root directory of the repository. Python autosubmission does not currently support private packages; packages referenced in requirements.txt which are not publicly available will cause the autosubmission action to fail.

注意

This action uses actions/setup-python to install Python. You must include a .python-version file in your repository to specify the Python version to be installed.

Further reading