Referencia de opciones de Dependabot

Informacióndel archivo dependabot.yml

En el archivo dependabot.yml se define cómo Dependabot mantiene las dependencias mediante actualizaciones de versión. Además, todas las opciones marcadas con un icono también cambian cómo Dependabot crea solicitudes de cambios para las actualizaciones de seguridad, excepto donde se usa target-branch.

El archivo de configuración dependabot.yml Dependabot, utiliza la sintaxis YAML. Si no estás familiarizado con YAML y quieres obtener más información, consulta Aprender YAML en cinco minutos.

Debe almacenar este archivo en el directorio .github del repositorio en la rama predeterminada. Cuando agrega o actualiza el archivo dependabot.yml, se activa una comprobación inmediata de las actualizaciones de la versión. Para obtener más información y un ejemplo, consulta Configuración de las actualizaciones de versiones de Dependabot.

Claves obligatorias

Opcionalmente, también puedes incluir una clave registries de nivel superior para definir los detalles de acceso de los registros privados; consultaClave registries de nivel superior.

# Basic `dependabot.yml` file with
# minimum configuration for two package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

# Basic `dependabot.yml` file with
# minimum configuration for two package managers

version: 2
updates:
  # Enable version updates for npm
  - package-ecosystem: "npm"
    # Look for `package.json` and `lock` files in the `root` directory
    directory: "/"
    # Check the npm registry for updates every day (weekdays)
    schedule:
      interval: "daily"

  # Enable version updates for Docker
  - package-ecosystem: "docker"
    # Look for a `Dockerfile` in the `root` directory
    directory: "/"
    # Check for updates once a week
    schedule:
      interval: "weekly"

Para obtener un ejemplo real de un archivo dependabot.yml, consulta el archivo de configuración propio de Dependabot.

allow

Se usa para definir exactamente qué dependencias mantener para un ecosistema de paquetes. A menudo se usa con la opción ignore. Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

Comportamiento predeterminado de Dependabot:

• Todas las dependencias definidas explícitamente en un manifiesto se mantienen actualizadas por las actualizaciones de versión.
• Las actualizaciones de seguridad actualizan todas las dependencias definidas en archivos de bloqueo con dependencias vulnerables.

Cuando se especifica allow, Dependabot usa el siguiente proceso:

1. Comprueba todas las dependencias permitidas explícitamente.

2. Después, filtra las dependencias o versiones omitidas.

   Si una dependencia coincide con una instrucción allow y ignore, se omite.

dependency-name (allow)

Para la mayoría de los administradores de paquetes, debes definir un valor que coincida con el nombre de la dependencia especificado en el archivo de bloqueo o manifiesto. Algunos sistemas tienen requisitos más complejos.

dependency-type (allow)

assignees

Especifica usuarios asignados individuales para todas las solicitudes de cambios generadas para un administrador de paquetes. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Las solicitudes de cambios se crean sin usuarios asignados.

Cuando se define assignees:

• Todas las solicitudes de cambios para las actualizaciones de versión se crean con los usuarios asignados elegidos.
• Todas las solicitudes de cambios para las actualizaciones de seguridad se crean con los usuarios asignados elegidos, a menos que target-branch defina las actualizaciones en una rama no predeterminada.

Los usuarios asignados deben tener acceso de escritura al repositorio. En el caso de los repositorios propiedad de la organización, los miembros de la organización con acceso de lectura también son usuarios asignados válidos.

commit-message

Define el formato para los mensajes de confirmación. Como los títulos de las solicitudes de cambios se escriben en función de los mensajes de confirmación, este valor también afecta a los títulos de las solicitudes de cambios. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Los mensajes de confirmación siguen patrones similares a los detectados en el repositorio.

Cuando se define commit-message:

• Todos los mensajes de confirmación siguen el patrón definido.
• Todos los mensajes de confirmación siguen el patrón definido, a menos que target-branch defina actualizaciones en una rama no predeterminada.

prefix

• Se usa para todos los mensajes de confirmación a menos que también se defina prefix-development.
• El valor puede tener hasta 50 caracteres.
• Dependabot inserta dos puntos después del prefijo antes de agregar el mensaje de confirmación principal cuando el valor termina con una letra, un número, un paréntesis de cierre o un corchete de cierre.
• Finaliza el valor con un carácter de espacio en blanco para no agregar los dos puntos.

prefix-development

Compatible con: bundler, composer, mix, maven, npm y pip.

• Solo se usa para los mensajes de confirmación que actualizan las dependencias del grupo de dependencias de desarrollo.
• De lo contrario, el parámetro se comporta exactamente como el parámetro prefix.

include

• Solo admite el valor scope
• Cuando se define, cualquier prefijo va seguido del tipo de las dependencias actualizadas en la confirmación: deps o deps-dev.

directories o directory

Opción obligatoria. Se usa para definir la ubicación de los manifiestos de paquetes para cada administrador de paquetes (por ejemplo, package.json o Gemfile). Si esta información, Dependabot no puede genera solicitudes de cambios para actualizaciones de versión. Para obtener ejemplos, consulta Definición de varias ubicaciones para archivos de manifiesto.

• Usa directory para definir un único directorio de manifiestos.
• Usa directories para definir una lista de varios directorios de manifiestos.
• Define directorios relativos a la raíz del repositorio para la mayoría de los administradores de paquetes.
• Para GitHub Actions, usa el valor /. Dependabot buscará en el directorio /.github/workflows, así como en el archivo action.yml/action.yaml desde el directorio raíz.

Si necesitas usar más de un bloque en el archivo de configuración a fin de definir actualizaciones para una sola rama de destino de un ecosistema, debes asegurarte de que todos los valores sean únicos y que los directorios definidos no se superpongan.

enable-beta-ecosystems

No se usa actualmente.

groups

Define reglas para crear uno o varios conjuntos de dependencias administradas por un administrador de paquetes, para agrupar las actualizaciones en menos solicitudes de cambios dirigidas. Para ejemplos, consulta Optimización de la creación de solicitudes de cambios para actualizaciones de versión de Dependabot.

Comportamiento predeterminado de Dependabot:

• Abre una única solicitud de cambios para cada dependencia que se deba actualizar a una versión más reciente para las actualizaciones de versión y para las actualizaciones de seguridad.

Cuando se usa groups para definir reglas:

• Todas las actualizaciones para dependencias que coinciden con una regla se combinan en una única solicitud de cambios.
• Si una dependencia coincide con más de una regla, se incluye en el primer grupo que coincide.
• Las dependencias obsoletas que no coinciden con una regla se actualizan en solicitudes de cambios individuales.

dependency-type (groups)

Compatible con: bundler, composer, mix, maven, npm y pip.

De manera predeterminada, un grupo incluirá todos los tipos de dependencias.

• Usa development para incluir solo las dependencias en el "Grupo de dependencias de desarrollo".
• Usa production para incluir solo las dependencias en el "Grupo de dependencias de producción".

patterns y exclude-patterns (groups)

Las dos opciones admiten el uso de * como comodín para definir coincidencias con nombres de dependencia. Si una dependencia coincide con un patrón y un patrón de exclusión, se excluye del grupo.

update-types (groups)

De manera predeterminada, un grupo incluirá actualizaciones para todas las versiones semánticas (SemVer). SemVer es un estándar aceptado para definir versiones de paquetes de software, con el formato x.y.z. Dependabot supone que las versiones con este formato siempre son major.minor.patch.

• Usa patch para incluir versiones de revisión.
• Usa minor para incluir versiones secundarias.
• Usa major para incluir versiones principales.

Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

ignore

Se usa con la opción allow para definir exactamente qué dependencias mantener para un ecosistema de paquetes. El Dependabot revisa las dependencias permitidas y después filtra cualquier dependencia o versión ignorada. Por tanto, una dependencia que coincida con una instrucción allow e ignore se omitirá. Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

Comportamiento predeterminado de Dependabot:

• Todas las dependencias definidas explícitamente en un manifiesto se mantienen actualizadas por las actualizaciones de versión.
• Las actualizaciones de seguridad actualizan todas las dependencias definidas en archivos de bloqueo con dependencias vulnerables.

Cuando se usa ignore, Dependabot utiliza el siguiente proceso:

1. Comprueba todas las dependencias permitidas explícitamente.

2. Después, filtra las dependencias o versiones omitidas.

   Si una dependencia coincide con una instrucción allow y ignore, se omite.

dependency-name (ignore)

Para la mayoría de los administradores de paquetes, debes definir un valor que coincida con el nombre de la dependencia especificado en el archivo de bloqueo o manifiesto. Algunos sistemas tienen requisitos más complejos.

versions (ignore)

Úsala para omitir versiones concretas o intervalos de versiones. Si quieres definir un rango, usa el patrón estándar para el administrador de paquetes. Por ejemplo:

• npm: usa ^1.0.0
• Bundler: usa ~> 2.0
• Docker: usa la sintaxis de la versiones de Ruby
• NuGet: usa 7.*

Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

update-types (ignore)

Especifica qué versiones semánticas (SemVer) se omitirán. SemVer es un estándar aceptado para definir versiones de paquetes de software, con el formato x.y.z. Dependabot supone que las versiones de este formulario siempre son major.minor.patch.

• Usa patch para incluir versiones de revisión.
• Usa minor para incluir versiones secundarias.
• Usa major para incluir versiones principales.

insecure-external-code-execution

Compatible con: bundler, mix y pip.

Permite que Dependabot ejecute código externo en el manifiesto durante las actualizaciones. Para obtener ejemplos, consulta Permiso para la ejecución de código externo.

Comportamiento predeterminado de Dependabot:

• Al conceder acceso a Dependabot a uno o varios registros, la ejecución de código externo se deshabilita automáticamente para proteger el código de los paquetes en peligro.
• Es posible que se produzca un error en las actualizaciones de versión sin la capacidad de ejecutar código.

Cuando se permite insecure-external-code-execution:

• Dependabot ejecutará código en el manifiesto como parte del proceso de actualización de la versión.
• El código solo tiene acceso a los administradores de paquetes de los registros asociados a ese valor de updates. No se permite el acceso a ninguno de los registros definidos en la configuración de registries de nivel superior.
• Esto debería permitir que la actualización sea correcta pero también que un paquete que se haya puesto en riesgo robe las credenciales u obtenga acceso a los registros configurados.

Valor admitido: allow.

labels

Especifica etiquetas propias para todas las solicitudes de cambios generadas para un administrador de paquetes. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Todas las solicitudes de cambios tienen una etiqueta dependencies.
• Si defines más de un administrador de paquetes, se agrega una etiqueta adicional para el ecosistema o el lenguaje a cada solicitud de cambios. Por ejemplo, java para actualizaciones de Gradle o submodules para actualizaciones de submódulo de Git.
• El Dependabot crea estas etiquetas predeterminadas automáticamente, de acuerdo lo necesite tu repositorio.

Cuando se define labels:

• Se usan las etiquetas especificadas en lugar de las predeterminadas.
• Si ninguna de estas etiquetas se define en el repositorio, entonces se ha ignorado.
• Puedes deshabilitar todas las etiquetas, incluidas las predeterminadas, mediante labels: [ ].

Configurar esta opción también afectará a las solicitudes de incorporación de cambios para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquetes, a menos que use target-branch para buscar actualizaciones de versión en una rama diferente a la predeterminada.

milestone

Asocia todas las solicitudes de cambios generadas para un administrador de paquetes con un hito. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• No se usan hitos.

Cuando se define milestone:

• Todas las solicitudes de cambios del administrador de paquetes se agregan al hito.

Valor admitido: identificador numérico de un hito.

open-pull-requests-limit

Cambia el límite máximo de solicitudes de cambios para las actualizaciones de versión abiertas en cualquier momento.

Comportamiento predeterminado de Dependabot:

• Si se abren cinco solicitudes de cambios con actualizaciones de versión, no se generan más solicitudes de cambios hasta que algunas de las abiertas se combinen o se cierren.
• Las actualizaciones de seguridad que tienen un límite separado e interno de diez solicitudes de cambios abiertas que no se puede modificar.

Cuando se define open-pull-requests-limit:

• Dependabot abre solicitudes de cambios hasta el valor entero definido.
• Puedes deshabilitar temporalmente las actualizaciones de versión de un administrador de paquetes si estableces esta opción en cero; consulta Deshabilitación de Dependabot version updates.

package-ecosystem

Opción obligatoria. Define un elemento package-ecosystem para cada administrador de paquetes que quieras que Dependabot supervise a fin de encontrar versiones nuevas. El repositorio también debe contener un archivo de bloqueo o de manifiesto de dependencias para cada administrador de paquetes; consulta Archivo dependabot.yml de ejemplo.

pull-request-branch-name.separator

Especifica un separador que se usará al generar nombres de rama. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Genera nombres de rama con el formato: dependabot/PACKAGE_MANAGER/DEPENDENCY

Cuando se define pull-request-branch-name.separator:

• Usa el carácter especificado en lugar de /.

Valores admitidos: "-", _, /

rebase-strategy

Deshabilita la fusión mediante cambio de base de la solicitud de cambios generada por Dependabot.

El comportamiento predeterminado de Dependabot es fusionar mediante cambio de base las solicitudes de cambios abiertas cuando Dependabot detecta cambios en una solicitud de cambios de actualización de seguridad o de versión. Dependabot comprueba si hay cambios cuando:

• La programación se ejecuta para comprobar si hay actualizaciones de versión.
• Vuelves a abrir una solicitud de cambios de Dependabot cerrada.
• Cambias el valor de target-branch en el archivo de configuración de Dependabot; consulta target-branch.
• Hay una solicitud de cambios de Dependabot en conflicto después de una inserción reciente en la rama de destino.

Cuando rebase-strategy se establece en disabled, Dependabot deja de fusionar mediante cambio de base las solicitudes de incorporación de cambios.

registries

Configura el acceso a los registros de paquetes privados para permitir que Dependabot actualice una gama más amplia de dependencias; consulta Configuración del acceso a registros privados para Dependabot y Guía para la configuración de registros privados para Dependabot.

Hay 2 ubicaciones en el archivo dependabot.yml donde puede usar la clave registries:

1. En el nivel superior, donde defines los registros privados que quieres usar y su información de acceso, consulta Configuración del acceso a registros privados para Dependabot.
2. Dentro de los bloques updates, donde puedes especificar qué registros privados debe usar cada administrador de paquetes.

El comportamiento predeterminado de Dependabot consiste en generar solicitudes de cambios solo para actualizar las dependencias almacenadas en registros accesibles públicamente.

Cuando el archivo de configuración de Dependabot tiene una sección registries de nivel superior, en la que se define el acceso a uno o varios registros privados, puedes configurar cada instancia de package-ecosystem para que use uno o varios de estos registros privados.

Cuando se define registries para un administrador de paquetes:

• Se comprueba cada registro privado especificado para un administrador de paquetes en busca de actualizaciones de versión y seguridad.
• Dependabot usa los detalles de acceso definidos en la sección registries de nivel superior.

Valores admitidos: REGISTRY_NAME o "*"

reviewers

Especifica revisores o equipos individuales de revisores para todas las solicitudes de cambios generadas para un administrador de paquetes. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Las solicitudes de cambios se crean sin revisores asignados.

Cuando se define reviewers:

• Todas las solicitudes de cambios para las actualizaciones de versión se crean con los revisores elegidos.
• Todas las solicitudes de cambios para las actualizaciones de seguridad se crean con los revisores elegidos, a menos que target-branch defina las actualizaciones en una rama no predeterminada.

Los revisores deben tener, como mínimo, acceso de lectura al repositorio.

schedule

Opción obligatoria. Define la frecuencia para comprobar si hay versiones nuevas para cada administrador de paquetes que configures con el parámetro interval. Opcionalmente, para intervalos diarios y semanales, puedes personalizar cuando Dependabot comprueba si hay actualizaciones. Para obtener ejemplos, consulta Optimización de la creación de solicitudes de cambios para actualizaciones de versión de Dependabot.

interval

Valores admitidos: daily, weekly o monthly

Cada administrador de paquetes debe definir un intervalo de programación.

• Usa daily para realizar la ejecución cada día de la semana, de lunes a viernes.
• Usa weekly para realizar la ejecución una vez a la semana, de manera predeterminada el lunes.
• Usa monthly para realizar la ejecución el primer día de cada mes.

Predeterminadamente, el Dependabot asigna una hora aleatoria para aplicar todas las actualizaciones en el archivo de configuración. Puedes usar los parámetros time y timezone para establecer un tiempo de ejecución específico para todos los intervalos.

day

Valores admitidos: monday, tuesday, wednesday, thursday, friday, saturday o sunday

Opcionalmente, ejecuta actualizaciones semanales para un administrador de paquetes en un día específico de la semana.

time

Formato: hh:mm

Opcionalmente, ejecuta todas las actualizaciones de un administrador de paquetes a una hora específica del día. De manera predeterminada, las horas se interpretan como UTC.

timezone

Especifica una zona horaria para el valor time.

El identificador de zona horaria debe coincidir con una zona horaria de la base de datos mantenida por iana; consulta Lista de zonas horarias de base de datos de tz.

target-branch

Define una rama específica para comprobar si hay actualizaciones de versión y para dirigir las solicitudes de cambios para las actualizaciones de versión. Para ejemplos, consulta Personalización de las solicitudes de cambios de Dependabot para ajustarlas a los procesos.

Comportamiento predeterminado de Dependabot:

• Dependabot usa la rama predeterminada para el repositorio; consulta Acerca de la rama predeterminada.

Cuando se define target-branch:

• Solo se comprueban si hay actualizaciones de versión en los archivos de manifiesto de la rama de destino.
• Todas las solicitudes de cambios para las actualizaciones de versión se abren con la rama especificada como destino.
• Las opciones definidas para package-ecosystem ya no se aplican a las actualizaciones de seguridad porque las actualizaciones de seguridad siempre usan la rama predeterminada para el repositorio.

vendor

Compatible con: solo bundler y gomod.

Indica a Dependabot que mantenga las dependencias delegadas a proveedores, así como las dependencias definidas por los archivos de manifiesto. Una dependencia se describe como "delegada a proveedores" o "en caché" al almacenar el código en el repositorio; consulta la documentación de bundle cache y la documentación de go mod vendor.

Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

Comportamiento predeterminado de Dependabot:

• Mantén solo las dependencias registradas en los archivos de manifiesto y bloqueo identificados para Bundler.
• Genera solicitudes de cambios de actualización de seguridad y versión que actualicen los números de versión registrados en los archivos de manifiesto y bloqueo.
• En el caso de los módulos de Go, las dependencias delegadas a proveedores se identifican y mantienen automáticamente como si vendor estuviera habilitado.

Cuando vendor está habilitado:

• Dependabot también mantiene las dependencias de Bundler que se almacenan en el directorio _vendor/cache_ del repositorio.
• Las solicitudes de cambios a veces contendrán actualizaciones de una dependencia almacenada en el repositorio.

Valores admitidos: true o false

versioning-strategy

Compatible con: bundler, cargo, composer, mix, npm, pip, pub

Define cómo Dependabot debe editar los archivos de manifiesto. Para ejemplos, consulta Control de qué dependencias actualiza Dependabot.

Comportamiento predeterminado de Dependabot:

• Intenta diferenciar entre dependencias de aplicación y biblioteca.
• Para las aplicaciones, aumenta siempre el requisito de versión mínima para que coincida con la versión nueva. Estrategia de increase.
• Para las bibliotecas, amplía los requisitos de versión permitida para que incluyan tanto la versión nueva como la anterior, siempre que sea posible. Estrategia de widen.

Cuando se define versioning-strategy, Dependabot usa la estrategia especificada.

Por ejemplo, si la versión actual es 1.0.0 y la restricción actual es ^1.0.0 las distintas estrategias generarían las siguientes actualizaciones:

Versión nueva 1.2.0

• increase: nueva restricción ^1.2.0
• increase-if-necessary: nueva restricción ^1.0.0
• widen: nueva restricción ^1.0.0

Versión nueva 2.0.0

• increase: nueva restricción ^2.0.0
• increase-if-necessary: nueva restricción ^2.0.0
• widen: nueva restricción >=1.0.0 <3.0.0

Clave registries de nivel superior

Especifica los detalles de autenticación que Dependabot puede utilizar para acceder a los registros de paquetes privados, incluidos los que se hospedan en GitLab o Bitbucket.

El valor de la clave registries es una matriz asociativa, de la cual cada elemento consiste en una clave que identifica un registro en particular y un valor que es una matriz asociativa que especifica la configuración que se requiere para acceder a dicho registro. El siguiente archivo dependabot.yml configura un registro identificado como dockerhub en la sección registries del archivo y, después, hace referencia a este en la sección updates del archivo.

# Minimal settings to update dependencies stored in one private registry

version: 2
registries:
  dockerhub: # Define access for a private registry
    type: docker-registry
    url: registry.hub.docker.com
    username: octocat
    password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
  - package-ecosystem: "docker"
    directory: "/docker-registry/dockerhub"
    registries:
      - dockerhub # Allow version updates for dependencies in this registry
    schedule:
      interval: "monthly"

# Minimal settings to update dependencies stored in one private registry

version: 2
registries:
  dockerhub: # Define access for a private registry
    type: docker-registry
    url: registry.hub.docker.com
    username: octocat
    password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
  - package-ecosystem: "docker"
    directory: "/docker-registry/dockerhub"
    registries:
      - dockerhub # Allow version updates for dependencies in this registry
    schedule:
      interval: "monthly"

Utilizarás las siguientes opciones para especificar la configuración de acceso. La configuración del registro debe contener un elemento type y otro url, y normalmente incluirán una combinación username y password, o un elemento token.

Para obtener información detallada sobre las opciones disponibles, así como recomendaciones y consejos al configurar registros privados, consulta Guía para la configuración de registros privados para Dependabot.

type y detalles de autenticación

Los parámetros usados para proporcionar detalles de autenticación para el acceso a un registro privado varían según el registro type.

Todos los datos confidenciales usados para la autenticación se deben almacenar de forma segura y hacerles referencia desde esa ubicación segura; consulta Configuración del acceso a registros privados para Dependabot.

url y replaces-base

El parámetro url define dónde acceder a un registro. Cuando se habilita el parámetro opcional replaces-base (true), Dependabot resuelve las dependencias mediante el valor url en lugar de la URL base de ese ecosistema concreto.