deps.yml

A deps.yml is only required if you need to make changes beyond what is configured automatically.

# deps.yml
version: 3  # required!
dependencies:
- type: python
  path: app/server/requirements.txt
- type: js

Lockfile updates

Most modern dependency managers have the concept of a "lockfile" (yarn.lock). This is how you save the exact version of your direct and transitive dependencies that your app should be using.

When your lockfile is outdated, deps will send you a single pull request that updates the entire lockfile. This single pull request will include in-range updates to all of your direct and transitive dependencies.

To disable lockfile updates, you can set enabled: false in your deps.yml.

# deps.yml
version: 3
dependencies:
- type: js
  lockfile_updates:
    enabled: false

Examples of supported lockfiles

• yarn.lock in Yarn
• package-lock.json in npm
• Pipfile.lock in Pipenv
• poetry.lock in poetry
• composer.lock in Composer

Manifest updates

A manifest is where you define your direct dependencies (like in package.json).

When an out-of-range update is available for a direct dependency, you'll get a pull request suggesting a new constraint to use. In-range updates will be delivered as lockfile updates.

You can disable manifest updates entirely:

# deps.yml
version: 3
dependencies:
- type: python
  manifest_updates:
    enabled: false

Examples of supported manifests

• package.json in npm
• Pipfile in Pipenv
• requirements.txt in Python/pip
• pyproject.toml in poetry
• composer.json in Composer

Disabling updates for a direct dependency

Use manifest_updates.filters to enable or disable updates on a per-dependency basis.

# deps.yml
version: 3
dependencies:
- type: python
  manifest_updates:
    # Filters are evaluated *in order*
    # so each dependency will use the first rule that it matches
    filters:
    - name: requests
      enabled: false
    # Typically your last filter will look like this,
    # which says any remaining matches should have updates enabled
    - name: .*
      enabled: true

Grouping related updates

You can also use manifest_updates.filters to group related updates, such as "react" and "react-dom". This way you'll get a single pull request that updates all of the react packages.

For example:

# deps.yml
version: 3
dependencies:
- type: python
  manifest_updates:
    filters:
    - name: react.*
      group: true
    - name: .*

Injecting commands (hooks)

# deps.yml
version: 3
dependencies:
- type: js
  settings:
    before_commit: npm run compile  # Only runs in CI

Customizing commit messages

Add commit message prefixes, suffixes, and trailers by providing your own template for the commit message. The template is rendered using Go's text/template package.

# deps.yml
version: 3
dependencies:
- type: js
  settings:
    ## Variables
    # Single line subject (ex. "Update x from 1.0 to 2.0")
    # {{.Subject}}
    # Expanded body description (if available)
    # {{.Body}}
    # Combined subject + \n\n + optional body
    # {{.SubjectAndBody}}

    # Default
    commit_message_template: "{{.SubjectAndBody}}"

    # Subject prefix example
    commit_message_template: "deps: {{.SubjectAndBody}}"

    # Simplified subject w/ suffix example
    commit_message_template: "{{.Subject}} (skip ci)"

    # Trailer example
    commit_message_template: |-
      {{.SubjectAndBody}}

      Changelog: updated

Environment variables

For each dependency type, you can set env variables that will be set when that component runs.

These must be strings!

# deps.yml
version: 3
dependencies:
- type: js
  env:
    NODE_ENV: production

Settings

Most components have settings to further specify how they work.

# deps.yml
version: 3
dependencies:
- type: js
  settings:
    github_labels:
    - dependencies

Settings can be more complex types and will be passed to the component as DEPS_SETTING_{NAME}={JSON encoded value}.

If you do not have a deps.yml, you can also pass settings manually (and for every component) by using an env variable in your CI. This is an easy way to apply the same GitHub PR labels to all updates, for example:

$ DEPS_SETTING_GITHUB_LABELS='["dependencies"]' deps ci

Filter settings

Settings can also be configured for specific dependencies via filters.

# deps.yml
version: 3
dependencies:
- type: python
  manifest_updates:
    filters:
    - name: requests
      enabled: false
      settings:
        github_labels:
        - requests
    - name: .*
      enabled: true