Dependency review

About dependency review

La revisión de dependencias te permite entender los cambios a las dependencias y el impacto de seguridad de estos cambios en cada solicitud de cambios. Proporciona una visualización fácil de entender para los cambios de dependencia con un diferencial importante en la pestaña "Archivos cambiados" de una solicitud de incorporación de cambios. La revisión de dependencias te informa sobre:

• Qué dependencias se agregaron, eliminaron o actualizaron junto con las fechas de lanzamiento
• Cuántos proyectos utilizan estos componentes
• Datos de las vulnerabilidades para estas dependencias

For pull requests that contain changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities.

Sometimes you might just want to update the version of one dependency in a manifest and generate a pull request. However, if the updated version of this direct dependency also has updated dependencies, your pull request may have more changes than you expected. The dependency review for each manifest and lock file provides an easy way to see what has changed, and whether any of the new dependency versions contain known vulnerabilities.

By checking the dependency reviews in a pull request, and changing any dependencies that are flagged as vulnerable, you can avoid vulnerabilities being added to your project. For more information about how dependency review works, see Revisar los cambios en las dependencias en un pull request.

Dependabot alerts will find vulnerabilities that are already in your dependencies, but it's much better to avoid introducing potential problems than to fix problems at a later date. For more information about Dependabot alerts, see Dependabot alerts.

Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see Ecosistemas de paquetes que soportan el gráfico de dependencias.

For more information on supply chain features available on GitHub, see Supply chain security.

Enabling dependency review

The dependency review feature becomes available when you enable the dependency graph. For more information, see Enabling the dependency graph for your enterprise."

About the Acción de revisión de dependencias

La "Acción de revisión de dependencias" hace referencia a la acción específica que puede informar sobre las diferencias en una solicitud de cambios dentro del contexto de GitHub Actions. Vea dependency-review-action. Puedes usar Acción de revisión de dependencias en el repositorio para aplicar revisiones de dependencias en las solicitudes de incorporación de cambios. La acción analiza las versiones vulnerables de las dependencias introducidas por los cambios de versión del paquete en las solicitudes de incorporación de cambios y le advierte sobre las vulnerabilidades de seguridad asociadas. Esto proporciona una mejor visibilidad de los cambios en una solicitud de incorporación de cambios y ayuda a evitar que se agreguen vulnerabilidades al repositorio.

De forma predeterminada, se producirá un error en la comprobación de Acción de revisión de dependencias si detecta paquetes vulnerables. Una comprobación con errores impide combinar una solicitud de incorporación de cambios si el propietario del repositorio requiere que se supere la comprobación de revisión de dependencias. Para más información, consulta Acerca de las ramas protegidas.

The action is available for all repositories that have GitHub Advanced Security enabled.

Los propietarios de la organización pueden implementar la revisión de dependencias a escala aplicando el uso de las variables de Acción de revisión de dependencias en los repositorios de la organización. Esto implica el uso de conjuntos de reglas de repositorio para los que establecerá las variables de Acción de revisión de dependencias como un flujo de trabajo necesario, lo que significa que las solicitudes de incorporación de cambios solo se pueden combinar una vez que el flujo de trabajo pasa todas las comprobaciones necesarias. Para más información, consulta Enforcing dependency review across an organization.

Los propietarios de la empresa y los usuarios con acceso de administrador a un repositorio pueden agregar Acción de revisión de dependencias a su empresa y repositorio, respectivamente.

The action uses the dependency review REST API to get the diff of dependency changes between the base commit and head commit. You can use the dependency review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see Puntos de conexión de la API de REST para la revisión de dependencias. The action also considers dependencies submitted via the API de envío de dependencias. For more information about the API de envío de dependencias, see Using the dependency submission API.

You can configure the Acción de revisión de dependencias to better suit your needs. For example, you can specify the severity level that will make the action fail. For more information, see Configuring the dependency review action.

Best practices for using the dependency review API and the API de envío de dependencias together

The dependency review API and the Acción de revisión de dependencias both work by comparing dependency changes in a pull request with the state of your dependencies in the head commit of your target branch.

If your repository only depends on statically defined dependencies in one of GitHub’s supported ecosystems, the dependency review API and the Acción de revisión de dependencias work consistently.

However, you may want your dependencies to be scanned during a build and then uploaded to the API de envío de dependencias. In this case, there are some best practices you should follow to ensure that you don’t introduce a race condition when running the processes for the dependency review API and the API de envío de dependencias, since it could result in missing data.

The best practices you should take will depend on whether you use GitHub Actions to access the API de envío de dependencias and the dependency review API, or whether you use direct API access.

Using GitHub Actions to access the API de envío de dependencias and the dependency review API

If you use GitHub Actions to access the API de envío de dependencias or the dependency review API:

• Make sure you run all of your dependency submission actions in the same GitHub Actions workflow as your Acción de revisión de dependencias. This will give you control over the order of execution, and it will ensure that dependency review will always work.
• If you do choose to run the Acción de revisión de dependencias separately, you should:
  • Set retry-on-snapshot-warnings to true.
  • Set retry-on-snapshot-warnings-timeout to slightly exceed the typical run time (in seconds) of your longest-running dependency submission action.

Using direct API access to the API de envío de dependencias and the dependency review API

If you don’t use GitHub Actions, and your code relies on direct access to the API de envío de dependencias and the dependency review API:

• Make sure you run the code that calls the API de envío de dependencias first, and then run the code that calls the dependency review API afterwards.
• If you do choose to run the code for the API de envío de dependencias and the dependency review API in parallel, you should implement a retry logic and note the following:
  • When there are snapshots missing for either side of the comparison, you will see an explanation for that in the x-github-dependency-graph-snapshot-warnings header (as a base64-encoded string). Therefore, if the header is non-empty, you should consider retrying.
  • Implement a retry logic with exponential backoff retries.
  • Implement a reasonable number of retries to account for the typical runtime of your dependency submission code.

Further reading

• Customizing your dependency review action configuration