Config files

Depfu now supports config files. 

The support is somewhat experimental and especially in combination with the settings UI, it may be possible to configure Depfu in a way that it will missbehave so please read this document carefully and make sure you're careful with especially the more dangerous options like automerging.

Config file structure

The config files are called .depfu.yml and contain a relatively flat list of options. To be able to address several different languages present in one folder (Bundler and Yarn in a Rails project, for example), these can be addressed as sub-structures in the config file. These will override global settings. Here's an example:

update_strategy: security

yarn:
  update_strategy: grouped
  grouped_update_schedule: weekly
  grouped_update_start_date: "2022-01-01"
  grouped_update_time: "6:00"

The allowed top level keys for package managers are:

  • bundler: - Ruby
  • npm: - JavaScript
  • yarn:  - JavaScript
  • hex: - Elixir
  • composer: - PHP

If you have several subdirectories of a repo activated, you can add config files to these subdirectories and the options specified there will override options from a config file sitting in the root. The more specific an option is specified, the higher the priority, so to speak.

Config files and UI settings

A changed config file will always override changes made in the UI. We will not prevent you from updating settings in the UI but will warn you that this might cause issues and that the changes will be overwritten as soon as the config file is changed.

Parser errors and wrong options

The format of the config file is described below. Should you make a typo that either makes the file invalid yaml or specifies wrong options that don't make sense, Depfu will show the errors in the settings UI. We know that's kind of an odd place and we're thinking about instead opening an issue on the repo to notify you, but a surprising number of GitHub/ GitLab repos have issues switched off, so we would've needed an alternative anyway.

Reference

update_strategy:

Options are:

  • individual - Depfu creates individual Pull/ Merge Requests for each updated dependency and it's updated subdependencies. This is Depfu's default and while it can be a bit noisy for large projects, it makes tracing problems with dependency updates so much easier.
  • grouped - Depfu creates updates on a regular schedule, batching together all dependency updates that happened up to that point. You can specify more options in this case:
  • security - Depfu only creates updates that are security relevant

grouped_update_schedule:

Can be one of daily , weekly , biweekly or monthly .

grouped_update_start_date:

Must be a valid ISO date, like 2020-11-01 - If you've set the schedule to daily, this doesn't make a lot of sense unless you want to start way ahead in the future.

  • weekly - we're taking the weekday of the specified date and either start on that weekday this week or next week.
  • biweekly - we're taking the date specified and jump forward by two weeks until we end up at a future date. This sounds a bit complicated but allows you to not only specify the weekday but also the particular week to run the update in.
  • monthly - to be able to stay on the specified weekday, we're doing the same as with biweekly but advance by four weeks. This option is a bit of a misnomer, but our thinking here is that staying on a stable weekday is more important than actually being super exact. (And we prevent edge cases like someone configuring this on the 29th of February)

grouped_update_time:

You can specifiy a time (in UTC time) at which the batched update will run, so that for example you can set this to run outside of your office hours. Make sure this is quoted as a string.

dev_update_strategy:

Allows you to specify a different update strategy for development dependencies

Can be one of individual , grouped , security - Same rules apply as with the general strategy

The scheduling options are named grouped_dev_update_schedule , grouped_dev_update_start_date etc.

indirect_update_strategy:

Only available for Ruby/Bundler at the moment, allows you to specify a different update strategy for indirect dependencies. Rest is same as dev_update_strategy

The scheduling options are named grouped_indirect_update_schedule , grouped_indirect_update_start_time etc.

reasonably_up_to_date:

can be true or false to tell Depfu to use or don't use our "Reasonably up to date" update strategies.

update_out_of_spec:

can be true or false to tell Depfu to update packages to versions outside of the specified version range. For example in npm, if a dependency is specified as "left-pad": "^1.3.0", Depfu will open up PRs for each update in the 1.x series but no update with a version of 2.0.0 or higher.

pull_request_limit:

The number of how many PRs Depfu is allowed to have open at the same time. Security updates will ignore this limit. The default is 7.

merge_request_limit:

pull_request_limit and merge_request_limit options are interchangeable so that GitLab users can use their own lingo.

branch_name_separator:

By default, Depfu separates branch names with slashes, for example like this "depfu/batch_indirect/2022-05-09" This confuses some build systems, so you can specify a different separator.

Can be one of / , - , . or _

automerge_strategy:

Allows you to specify if Pull/ Merge Requests should be automatically merged on a successful (green) CI build. Please be careful with this option. Depfu cannot and will not take any responsibility if your application goes down because of a botched dependency update. You need to make sure that your test suite is thorough enough to catch issues caused by broken dependencies. (Or alternatively: you simply have good rollback strategies)

Options are:

  • off - Default
  • patch - Only automerge if new version is only a patch update (say 1.3.3 to 1.3.4)
  • minor - Only automerge if new version is only a minor version update (say 1.3.3 to 1.4.0)
  • major - Automerge all updates

automerge_dev_strategy:

The less dangerous option as this only automerges development dependencies. Still, please be careful.

Options are the same as on automerge_strategy

automerge_method:

Use the merge method that should be used when triggering the merge.

Options are: rebase , squash , merge

engine_update_strategy:

Should we try to update the runtime/engine/language implementation such as your Ruby version, your node version, your PHP version?

Options are:

  • off - Please don't update
  • minor - Only update within the current major version. This may have slightly different meanings depending on  the languge. For example, Ruby sort of treats the "semantic" minor version as a sort of major release. New features and potential incompatibilities are introduced on what semantic versioning would call a minor version (Ruby 2.6 > Ruby 2.7 or Ruby 3.0 > Ruby 3.1 for example), so we try to honor that by only updating patch versions for Ruby on this setting
  • major - Upgrade to latest version all the time regardless of compatibility

commit_message:

Allows you to customise your commit message, for example if you want to use "conventional commit" messages. This particular configuration is for individual updates. Please note that even if you have set your update strategy to grouped, you'd need to customise this setting for incoming security updates.

You can use variables in the form of {{variable}} within the text. Available here:{{dependency}} - name of the dependency that will get updated, {{version}} - version the dependency will be updated to.

commit_message_grouped:

Allows you to customise the commit message for grouped updates, if you have specified your update strategy to group updates together. 

The available variables here are {{update_type} - "all", "all indirect", "all development" depending on what kind of dependencies are updated, {{project_type}} - the used package manager, {{date}} the date of the update.

labels:

Specify some labels that will be added to all Pull/ Merge Requests. Please note that these labels must exist, we're not automatically adding them. 

Can be a comma separated list

security_labels:

Specifiy labels that will be added to security updates. Please note that these labels must exist, we're not automatically adding them.

Can be a comma separated list

auto_assign:

Specify user names of users that will be automatically assigned to the Pull/ Merge Request. We're not checking the user names so this will fail silently if the users don't exist.

Can be a comma separated list

auto_review_assign:

Specify user names of users that will be automatically assigned as reviewers to the Pull/ Merge Request. 

auto_review_team_assign: (Only GitHub)

Specify team names that automatically get assigned to review the PR.

Still need help? Contact Us Contact Us