Opciones de configuración para actualizaciones de dependencias

Acerca del archivo dependabot.yml

El archivo de configuración del Dependabot de GitHub, dependabot.yml, utiliza la sintaxis YAML. Si eres nuevo en YAML y deseas conocer más, consulta "Aprender YAML en cinco minutos".

Debes almacenar este archivo en el directorio .github de tu repositorio. Cuando agregas o actualizas el archivo dependabot.yml, esto activa una revisión inmediata de las actualizaciones de la versión. Cualquier opción que también afecte a las actualizaciones de seguridad se utilizará en la siguiente ocasión que una alerta de seguridad active una solicitud de extracción para una alerta de seguridad. Para obtener más información, consulta las secciónes "Habilitar e inhabilitar las actualizaciones de versión" y "Configurar las Actualizaciones de seguridad del Dependabot de GitHub".

Opciones de configuración para dependabot.yml

El archivo dependabot.yml debe comenzar con version: 2, seguido de un conjunto de updates.

Estas opciones caen a groso modo en las siguientes categorías.

• Opciones de configuración esenciales que debes incluir en todas las configuraciones: package-ecosystem, directory,schedule.interval.
• Opciones para personalizar el calendario de actualización: schedule.time, schedule.timezone, schedule.day.
• Opciones para controlar qué dependencias se actualizan: allow, ignore.
• Opciones para agregar metadatos a las solicitudes de extracción: reviewers, assignees, labels, milestone.
• Opciones para cambiar el comportamiento de las solicitudes de extracción: target-branch, versioning-strategy, commit-message, rebase-strategy, pull-request-branch-name.separator.

Adicionalmente, la opción open-pull-requests-limit cambia la cantidad máxima de solicitudes de extracción para las actualizaciones de versión que puede abrir el Dependabot de GitHub.

package-ecosystem

Requerido Agregas un elemento de package-ecosystem para cada administrador de paquetes que quieras que el Dependabot de GitHub monitoree para revisar si hay nuevas versiones. El repositorio también debe contener un manifiesto de dependencia o archivo fijado de estos administradores de paquete.

• Bundler: bundler
• Cargo: cargo
• Composer: composer
• Docker: docker
• Elm: elm
• git submodule: gitsubmodule
• GitHub Actions: github-actions
• Go modules: gomod
• Gradle: gradle
• Maven: maven
• Mix: mix
• npm: npm
• NuGet: nuget
• pip: pip
• Terraform: terraform

# Basic set up for three package managers

version: 2
updates:

  # Maintain dependencies for GitHub Actions
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"

  # Maintain dependencies for npm
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"

  # Maintain dependencies for Composer
  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"

directorio

Requerido Debes definir la ubicación de los manifiestos de paquete para cada administrador de paquete (por ejemplo, el package.json o Gemfile). Tú definierás el directorio relativo a la raíz del repositorio para todos los ecosistemas, menos para GitHub Actions. Para GitHub Actions, configura el directorio para que sea / y así revisar los archivos de flujo de trabajo en .github/workflows.

# Specify location of manifest files for each package manager

version: 2
updates:
  - package-ecosystem: "composer"
    # Files stored in repository root
    directory: "/"
    schedule:
      interval: "daily"

  - package-ecosystem: "npm"
    # Files stored in `app` directory
    directory: "/app"
    schedule:
      interval: "daily"

  - package-ecosystem: "github-actions"
    # Workflow files stored in the
    # default location of `.github/workflows`
    directory: "/"
    schedule:
      interval: "daily"

schedule.interval

Requerido Debes definir qué tan a menudo se debe revisar si hay nuevas versiones y levantar solicitudes de extracción para las actualizaciones de versión en cada administrador de paquetes. Predeterminadamente, esto ocurre a las 5am UTC. Para modificar esto, utiliza schedule.time and schedule.timezone.

• daily—se ejecuta en cada día de la semana, de Lunes a Viernes.
• weekly—se ejecuta una vez cada semana. Predeterminadamente, esto ocurre los lunes. Para modificar esto, utiliza schedule.day.
• monthly—se ejecuta una vez al mes. Esto ocurre en el primer día de cada mes.

# Set update schedule for each package manager

version: 2
updates:

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      # Check for updates to GitHub Actions every weekday
      interval: "daily"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      # Check for updates managed by Composer once a week
      interval: "weekly"

allow

Predeterminadamente, todas las dependencias que se definen explícitamente en un manifiesto o archivo fijado se mantienen actualizadas. Puedes utilizar allow e ignore para personalizar qué dependencias quieres mantener con las actualizaciones de versión. El Dependabot de GitHub revisa las dependencias permitidas y después filtra cualquier dependencia o versión ignorada. Así que se ignorará cualquier dependencia que empate tanto con allow como con ignore.

Utiliza la opción allow para personalizar qué dependencias se actualizan. Esto no impacta en las actualizaciones de seguridad para las dependencias vulnerables. Puedes utilizar las siguientes opciones:

• dependency-name—se utiliza para permitir actualizaciones para las dependencias con nombres coincidentes, opcionalmente, utiliza * para empatar cero o más caracteres. Para las dependencias de Java, el formato del atributo dependency-name es: groupId:artifactId, por ejemplo: org.kohsuke:github-api.

• dependency-type—utilízalo para permitir actualizaciones para dependencias de tipos específicos.

  Tipos de dependencia	Administradores de paquete compatibles	Permitir actualizaciones
  direct	Todas	Todas las dependencias definidas explícitamente.
  indirect	bundler, pip, composer, cargo	Las dependencias de las dependencias directas (también conocidas como sub-dependencias, o dependencias transitorias).
  todos	Todas	Todas las dependencias definidas explícitamente. Para bundler, pip, composer, cargo, también las dependencias de las dependencias directas.
  production	bundler, composer, mix, maven, npm, pip	Únicamente las dependencias en el "Grupo de dependencias del producto".
  development	bundler, composer, mix, maven, npm, pip	Únicamente las dependencias en el "Grupo de dependencias de desarrollo".

# Customizing the dependencies to maintain with `allow`

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow updates for Lodash
      - dependency-name: "lodash"
      # Allow updates for React and any packages starting "react"
      - dependency-name: "react*"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow both direct and indirect updates for all packages
      - dependency-type: "all"

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    allow:
      # Allow only direct updates for
      # Django and any packages starting "django"
      - dependency-name: "django*"
        dependency-type: "direct"
      # Allow only production updates for Sphinx
      - dependency-name: "sphinx"
        dependency-type: "production"

asignatarios

Utiliza assignees para especificar a los asignados individuales para todas las solicitudes de extracción levantadas para un administrador de paquete.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Specify assignees for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Add assignees
    assignees:
      - "octocat"

commit-message

Predeterminadamente, el Dependabot de GitHub intenta detectar tus preferencias de mensajes de confirmación y utiliza patrones similares. Utiliza la opcióncommit-message para especificar tus preferencias explícitamente.

Opciones compatibles

• prefix especifica un prefijo para todos los mensajes de confirmación.
• prefix-development especifica un prefijo separado para todos los mensajes de confirmación que actualizan dependencias en el grupo de dependencias de desarrollo. Cuando especificas un valor para esta opción, prefix se utiliza únicamente para las actualizaciones a las dependencias en el grupo de dependencias de producción. Esto es compatible con: bundler, composer, mix, maven, npm, y pip.
• include: "scope" especifica que cualquier prefijo es sucedido por una lista de dependencias actualizadas en la confirmación.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Customizing commit messages

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    commit-message:
      # Prefix all commit messages with "npm"
      prefix: "npm"

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    # Prefix all commit messages with "Composer"
    # include a list of updated dependencies
    commit-message:
      prefix: "Composer"
      include: "scope"

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Include a list of updated dependencies
    # with a prefix determined by the dependency group
    commit-message:
      prefix: "pip prod"
      prefix-development: "pip dev"
      include: "scope"

ignore

Revisar por preferencias ignoradas existentes

Antes de que agreges una opción de ignore al archivo de configuración, revisa si has utilizado previamente cualquiera de los comandos de @dependabot ignore en una solicitud de extracción de actualizaciones de seguridad o de versión. El Dependabot de GitHub almacena estas preferencias para cada administrador de paquetes centralmente, y esta información se sobreescribe mediante la opción ignore. Para obtener más información acerca de los comandos de @dependabot ignore, consulta la sección "Administrar las solicitudes de extracción para las actualizaciones de dependencias".

Puedes revisar si un repositorio ha almacenado las preferencias si buscas dicho repositorio con "@dependabot ignore" in:comments. Si revias alguna solicitud de extracción en los resultados, puedes decidir si quieres o no especificar esas dependencias o versiones ignoradas en el archivo de configuración.

Especificar dependencias y versiones para ignorar

Predeterminadamente, todas las dependencias que se definen explícitamente en un manifiesto o archivo fijado se mantienen actualizadas. Puedes utilizar allow e ignore para personalizar qué dependencias quieres mantener con las actualizaciones de versión. El Dependabot de GitHub revisa las dependencias permitidas y después filtra cualquier dependencia o versión ignorada. Así que se ignorará cualquier dependencia que empate tanto con allow como con ignore.

Puedes utilizar la opción ignore para personalizar qué dependencias se actualizarán. La opción ignore es compatible con las siguientes opciones.

• dependency-name—se utiliza para ignorar actualizaciones para las dependencias con nombres coincidentes, opcionalmente, utiliza * para empatar cero o más caracteres. Para las dependencias de Java, el formato del atributo dependency-name es: groupId:artifactId, por ejemplo: org.kohsuke:github-api.
• versions—se utiliza para ignorar versiones o rangos específicos de las versiones. Si quieres definir un rango, utiliza el patrón estándar del administrador de paquetes (por ejemplo: ^1.0.0 para npm, o ~> 2.0 para Bundler).

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Customizing the dependencies to maintain with `ignore`

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    ignore:
      - dependency-name: "express"
        # For Express, ignore all updates for version 4 and 5
        versions: ["4.x", "5.x"]
        # For Loadash, ignore all updates
      - dependency-name: "loadash"

etiquetas

Predeterminadamente, el Dependabot de GitHub levanta todas las solicitudes de extracción con la etiqueta dependencies. Si se define más de un administrador de paquetes, incluye una etiqueta adicional en cada una de las solicitudes de extracción. Esto indica qué lenguaje o ecosistema actualizará la solicitud de extracción, por ejemplo: java para las actualizaciones de Gradle submodules para las actualizaciones de los submódulos de git. El Dependabot de GitHub crea estas etiquetas predeterminadas automáticamente, de acuerdo lo necesite tu repositorio.

Utiliza labels para anular las etiquetas predeterminadas y especificar las etiquetas alternas para todas las solicitudes de extracción que se levante para un administrador de paquete. Si ninguna de estas etiquetas se define en el repositorio, entonces se ha ignorado. Para inhabilitar todas las etiquetas, incluyendo aquellas predeterminadas, utiliza labels: [ ].

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Specify labels for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Specify labels for npm pull requests
    labels:
      - "npm"
      - "dependencies"

hito

Utiliza milestone para asociar todas las solicitudes de extracción que se han levantado para un administrador de paquete con un hito. Necesitas especificar el identificador numérico del hito y, no así, su etiqueta. Si ves un hito, la parte final de la URL de la página, después de milestone, es el identificador. Por ejemplo: https://github.com/<org>/<repo>/milestone/3.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Specify a milestone for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Associate pull requests with milestone "4"
    milestone: 4

open-pull-requests-limit

Predeterminadamente, Dependabot de GitHub abre un máximo de cinco solicitudes de extracción para las actualizaciones de versión. Una vez que haya cinco solicitudes de extracción abiertas, las nuevas solicitudes se bloquearán hasta que fusiones o cierres alguna de las que están abiertas. Utiliza open-pull-requests-limit para cambiar este límite. Esto también proporciona una forma simple de inhabilitar temporalmente las actualizaciones de versión para un administrador de paquete.

Esta opción no tiene impacto en las actualizaciones de seguridad que tienen un límite separado e interno de diez solicitudes de extracción abiertas.

# Changing the number of open pull requests allowed

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Disable version updates for npm dependencies
    open-pull-requests-limit: 0

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Allow up to 10 open pull requests for pip dependencies
    open-pull-requests-limit: 10

pull-request-branch-name.separator

El Dependabot de GitHub genera una rama para cada solicitud de extracción. Cada nombre de rama incluye dependabot, y el administrador de paquete y la dependencia que se actualizaron. Predeterminadamente, estas partes están separadas por un símbolo de /, por ejemplo: dependabot/npm_and_yarn/next_js/acorn-6.4.1.

Utiliza pull-request-branch-name.separator para especificar un separador diferente. Este puede ser alguno de entre: "-", _ o /. El símbolo de guión debe estar entre comillas porque, de lo contrario, se interpretará como que está declarando una lista YAML vacía.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Specifying a different separator for branch names

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    pull-request-branch-name:
      # Separate sections of the branch name with a hyphen
      # for example, `dependabot-npm_and_yarn-next_js-acorn-6.4.1`
      separator: "-"

rebase-strategy

Predeterminadamente, el Dependabot de GitHub rebasa automáticamente las solicitudes de extracción abiertas cuando detecta conflictos. Utiliza rebase-strategy para inhabilitar este comportamiento.

Estrategias de rebase disponibles

• disabled para inhabilitar el rebase automático.
• auto para utilizar el comportamiento predeterminado y rebasar las solicitudes de extracción abiertas cuando se detecten conflictos.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Disabling automatic rebasing

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Disable rebasing for npm pull requests
    rebase-strategy: "disabled"

reviewers

Utiliza reviewers para especificar los revisores o equipos individuales de revisores para las solicitudes de extracción que se levantaron para un administrador de paquete. Debes utilizar el nombre completo del equipo, incluyendo la organización, como si lo estuvieras @mencionando.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

# Specify reviewers for pull requests

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Add reviewers
    reviewers:
      - "octocat"
      - "my-username"
      - "my-org/python-team"

schedule.day

Cuando configuras un calendario de actualización en weekly, predeterminadamente, el Dependabot de GitHub revisa las nuevas versiones los lunes a las 05:00 UTC. Utiliza schedule.day para especificar un día alterno para revisar si hay actualizaciones.

Valores compatibles

• monday
• tuesday
• wednesday
• thursday
• friday
• saturday
• sunday

# Specify the day for weekly checks

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      # Check for npm updates on Sundays
      day: "sunday"

schedule.time

Predeterminadamente, el Dependabot de GitHub revisa si hay nuevas versiones a las 05:00 UTC. Utiliza schedule.time para especificar una hora alterna para revisar si hay actualizaciones (formato: hh:mm).

# Set a time for checks
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
      # Check for npm updates at 9am UTC
      time: "09:00"

schedule.timezone

Predeterminadamente, el Dependabot de GitHub revisa si hay nuevas versiones a las 05:00 UTC. Utiliza schedule.timezone para especificar un huso horario alternativo. El identificador de zona debe ser tomado de la base de datos de Husos Horarios que mantiene iana. Para obtener más información, consulta la Lista de bases de datos tz para husos horarios.

# Specify the timezone for checks

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
      time: "09:00"
      # Use Japan Standard Time (UTC +09:00)
      timezone: "Asia/Tokyo"

target-branch

Predeterminadamente, el Dependabot de GitHub revisa si hay archivos de manifiesto en las ramas predeterminadas y levanta solicitudes de extracción para las actualizaciones de versión contra dicha rama. Utiliza target-branch para especificar una rama diferente para los archivos de manifiesto y para las solicitudes de extracción. Cuando utilizas esta opción, la configuración para este administrador de paquete ya no afectará ninguna solicitud de extracción que se haya levantado para las actualizaciones de seguridad.

# Specify a non-default branch for pull requests for pip

version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Raise pull requests for version updates
    # to pip against the `develop` branch
    target-branch: "develop"
    # Labels on pull requests for version updates only
    labels:
      - "pip dependencies"

  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
      # Check for npm updates on Sundays
      day: "sunday"
    # Labels on pull requests for security and version updates
    labels:
      - "npm dependencies"

versioning-strategy

Cuando el Dependabot de GitHub edita un archivo de manifiesto para actualizar una versión, utiliza las siguientes estrategias generales:

• Para las apps, los requisitos de versión se incrementan, por ejemplo: npm, pip y Composer.
• Para las bibliotecas, el rango de versiones se amplía, por ejemplo: Bundler y Cargo.

Utiliza la opción versioning-strategy para cambiar este comportamiento para los administradores de paquete compatibles.

Configurar esta opción también afectará a las solicitudes de extracción para las actualizaciones de seguridad en los archivos de manifiesto de este administrador de paquete, a menos de que utilices target-branch para revisar las actualizaciones de versión en una rama diferente a la predeterminada.

Estrategias de actualización disponibles

# Customizing the manifest version strategy

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # Update the npm manifest file to relax
    # the version requirements
    versioning-strategy: widen

  - package-ecosystem: "composer"
    directory: "/"
    schedule:
      interval: "daily"
    # Increase the version requirements for Composer
    # only when required
    versioning-strategy: increase-if-necessary

  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    # Only allow updates to the lockfile for pip and
    # ignore any version updates that affect the manifest
    versioning-strategy: lockfile-only