Set-up and configuration of your Violinist monitoring.
All configuration of Violinist is optional. All configuration have default values, and if you do nothing, we will try to update in the way we feel is most sensible for most projects.
To provide a flexible way to configure Violinist, we have opted to use the extra
part of the composer.json schema.
A complete composer.json with all example values filled in (with their default values) are provided here for reference. To read about the different parts, click on their link counterpart below.
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"allow_list": [],
"allow_update_indirect_with_direct": 0,
"allow_updates_beyond_constraint": 1,
"always_allow_direct_dependencies": 0,
"always_update_all": 0,
"assignees": [],
"automerge": 0,
"automerge_security": 0,
"blocklist": [],
"branch_prefix": "",
"bundled_packages": {},
"check_only_direct_dependencies": 1,
"commit_message_convention": "",
"default_branch": "",
"labels": [],
"labels_security": [],
"number_of_concurrent_updates": 0,
"one_pull_request_per_package": 0,
"run_scripts": 1,
"security_updates_only": 0,
"timeframe_disallowed": 0,
"timezone": "+0000",
"update_dev_dependencies": 1,
"update_with_dependencies": 1
}
}
}
The branch name is named after the name of the package being updated, and the version you update from and to.
For example, if violinist finds out it wants to update your dependency psr/log from version 1.0.0 to 1.1.4 it would create the branch psrlog100114
.
If you want your branches to be named differently, you might be interested in specifying a branch prefix.
Violinist will try to keep the PR and its branch up to date. So if you push changes to your default branch, the PR becomes out of date. To make sure the PR can be still merged, violinist will force-push the branch to be up to date. This also means you should avoid working on a violinist branch, since your work might end up being overwritten by a force push.
If you want to add additional changes to a PR created by violinist you can start a new branch from the PR branch and work in that branch without worrying about losing your work.
To identify the updates that are available, violinist will run the following command:
composer outdated -D -m
You can read more about this command on the official composer website
The two options mean as follows:
--direct (-D): Restricts the list of packages to your direct dependencies.
--minor-only (-m): Only shows packages that have minor SemVer-compatible updates.
There are still several ways this can be manipulated. See the config options for details. For example, If you set the option check_only_direct_dependencies to 0
the --direct
flag will not be used.
The default command for updating packages with violinist are the following:
composer update vendor/package --with-dependencies
If you do not want violinist to update with dependencies, you can use the configuration option update_with_dependencies and set this to 0
.
If you want to update a package bundled with another package, you probably want to have a look at the option bundled_packages.
Note! Config branches are only available on the agency and enterprise plans.
It’s possible to have more than one instance of a project on violinist with different update strategies. Config branches indicates which branch will be used to read the violinist config. By default, this will be read from the same branch the updates are targeting. But using config branches you can overrides this. This can be useful for a couple of different reasons:
customer1
and customer 2 in branch customer2
. If that is the case you might want to have automated merge requests towards both branches.main
(using options security_updates_only
, default_branch
and automerge
. But in addition maybe you want violinist to open regular merge requests towards develop
without automerge
and with all dependencies.When you add a new project to violinist, you will have the option to choose a config branch together with setting the URL to your project or choosing a PHP version.
Note! This option would only be enabled if you are on a plan that support config branches. Otherwise the option would appear as disabled.
As the name suggests, the config branch will be used to check out a specific branch, and then read the violinist config from there. If this was used because there is no violinist config in the main branch, well, then there would be no place to read the config branch from, would there?
This documentation is open source. If you find a typo or you feel something is explained badly you can contribute to making it better!
The source can be found at https://github.com/violinist-dev/docs/
Sometimes your project or a dependency actually requires a PHP extension. Since this is a requirement, your updates can then fail either upon installing your project, or when updating it. For this reason, it might be useful to know what extensions violinist has available when checking for updates in your project.
This is the current output for the PHP 7.4 image of the command php -m
:
$ php -m
[PHP Modules]
apcu
bcmath
bz2
calendar
Core
ctype
curl
date
decimal
dom
exif
fileinfo
filter
ftp
gd
gmp
hash
iconv
imagick
imap
intl
json
ldap
libxml
mailparse
mbstring
memcached
mongodb
msgpack
mysqli
mysqlnd
openssl
pcntl
pcre
PDO
pdo_mysql
pdo_pgsql
pdo_sqlite
pdo_sqlsrv
Phar
posix
rdkafka
readline
redis
Reflection
session
SimpleXML
soap
sockets
sodium
SPL
sqlite3
sqlsrv
standard
tokenizer
uuid
xml
xmlreader
xmlrpc
xmlwriter
xsl
yaml
Zend OPcache
zip
zlib
[Zend Modules]
Zend OPcache
To perform updates to projects added on violinist.io we require access to the source code of the projects. Access in this context means access to do a full checkout of the code repository.
When the update jobs are being run, the full source will be checked out. This source code is not stored or cached, and the containers where the source code is checked out are destroyed and are never re-used.
Public repositories are theoretically open to be accessed by anyone. However, if you want to add a public repository to violinist.io we require you to administer the repository in question. The reason for this is to avoid creating unwanted pull requests from a random user, when the administrators of a project would not want this activity themselves.
Private repositories must be added by a user that has access to administer the repository. Keep in mind that when you add a repository, the user you are logged in with will also be seen as the author of pull/merge requests to this repository. For this reason, many violinist users (for example agencies) use a bot user to add their repositories to violinist.io
name: allow_list
type: array
default: []
{
"name": "company/project",
"extra": {
"violinist": {
"allow_list": []
}
}
}
An array of packages to explicitly allow when updating packages with violinist. Defaults to nothing, which means all available updates will be attempted. This means that putting one package on the allow list will block all other updates from being attempted, while having zero packages on the allow list will not filter any of the updates.
Note! When using in combination with blocklist, the updates will first be filtered through the allow list, and then it will apply block list rules. This means you can explicitly allow
symfony/*
while still addingsymfony/yaml
to the block list.
Note! This option has no effect if used in combination with always_update_all.
Some projects only want to allow updates to specific packages. This can be because you use other tools or processes to update the rest of your dependencies, or maybe you only care about updating one or some of the packages in your project.
If you want to add a project to the allow list, you can add some extra information into your composer.json.
Say you wanted violinist to only update vendor/package1
in your project, even if you had a bunch of other dependencies. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "^1.4.0",
"vendor/package2": "^1.4.0",
"vendor/package3": "^1.4.0",
"vendor/package4": "^1.4.0",
"vendor/package5": "^1.4.0",
"vendor/package6": "^1.4.0",
"vendor/package7": "^1.4.0"
}
}
To make sure violinist only even tries to update vendor/package1
you simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "^1.4.0",
"vendor/package2": "^1.4.0",
"vendor/package3": "^1.4.0",
"vendor/package4": "^1.4.0",
"vendor/package5": "^1.4.0",
"vendor/package6": "^1.4.0",
"vendor/package7": "^1.4.0"
},
"extra": {
"violinist": {
"allow_list": [
"vendor/package1"
]
}
}
}
This will make violinist only create pull/merge requests for vendor/package1
even if there are ever so many updates to all of the other packages.
You can also use wildcards in your allow list. Examples could be vendor/*
or vendor/prefix_*
.
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0"
},
"extra": {
"violinist": {
"allow_list": [
"vendor/*",
"vendor/prefix_*"
]
}
}
}
name: allow_update_indirect_with_direct
type: int
default: 0
{
"name": "company/project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"allow_update_indirect_with_direct": 0
}
}
}
Indicates that you want violinist to update your dependencies, even if your direct dependency does not have a new version, but at least one package in the dependency tree descending from a direct dependency has an update available.
Note! This setting has no effect if
always_update_all
is enabled.
By default, violinist will only update your dependencies if one of your direct dependencies has an update available. However, if a transative dependency has an update, it will not be updated until the direct dependency that introduce this dependency has an update. This option changes that.
This way, composer update vendor/package --with-dependencies
will run, regardless of the package having an update or not, and therefore also then update any (one or several) transative dependencies of vendor/package
.
Say you are trying out violinist and are duty fully merging all updates that comes in for a couple of weeks. And one day you decide to run composer update
manually. Surprisingly you find out that there are several updates applied. How can that be? You have been using violinist and have merged all available updates?
The reason is violinist only updates direct dependencies (unless you set check_only_direct_dependencies to 0). So if one of your dependencies is in it’s final version, and no more versions will be released, that final version can still depend on packages that receive weekly updates. Some people would therefore prefer to run the command composer update vendor/package --with-dependencies
even if vendor/package
has no updates, but the transitive dependencies from that package has updates.
This is different than check_only_direct_dependencies set to 0, since check_only_direct_dependencies
set to 0 would produce one merge request per direct or indirect dependency. While this option (allow_update_indirect_with_direct
) will only have merge requests for direct dependencies, some with actual updates to the direct dependency, and some only to one or more of the dependencies of a direct dependency.
If this sounds like the configuration you want, you would change your composer.json
like so:
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"allow_update_indirect_with_direct": 1
}
}
}
Note! This setting has no effect if
always_update_all
is enabled.
name: allow_updates_beyond_constraint
type: int
default: 1
{
"name": "company/project",
"extra": {
"violinist": {
"allow_updates_beyond_constraint": 1
}
}
}
Indicate whether or not we can try to update a package even if it is beyond the range specified in composer.json. Defaults to 1 (true).
Strictly speaking, if your composer.json specifies that you want to have the package vendor/package
in the version range ~1.0.0
, then composer will install all version in the range 1.0.x, but refuse to update it to 1.1.0. Some times this is what you want. But many times, a new version at 1.1.0 will include new features and be backwards compatible. So maybe you actually might want to start using that version instead? This is what the option for allowing to update beyond your version constraint does.
Say you depend on the project vendor/package
in range ~1.0.0
. And say the latest version is 1.1.0. And say you actually do not want to receive this update via Violinist. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
}
}
To make Violinist stop trying to update vendor/package
(and all other pages) beyond your specified version range you simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"allow_updates_beyond_constraint": 0
}
}
}
name: always_allow_direct_dependencies
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"always_allow_direct_dependencies": 0
}
}
}
Indicate if you want violinist to always allow packages that are direct dependencies, without explicitly putting each one on the allow list.
If your project is set to update both direct and indirect dependencies (by having the option check_only_direct_dependencies
set to 0), maybe what you are actually after is updating the direct dependencies plus one or two indirect ones. To achieve this you could of course explicitly list all the packages you want updated using allow_list
. But you could also use the option always_allow_direct_dependencies
to automatically allow all direct dependencies, and then explicitly allow one or two packages in addition to that.
Let’s say your project looks like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "~1.0.0",
"othervendor/otherpackage": "^2.0.7"
}
}
And then, maybe othervendor/otherpackage
has a bunch of indirect dependencies. And you don’t want a merge request for every update, but if there are updates to the indirect dependency third/module
then you actually do want a merge request for that.
To achieve this with violinist, you can do this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "~1.0.0",
"othervendor/otherpackage": "^2.0.7"
},
"extra": {
"violinist": {
"always_allow_direct_dependencies": 1,
"check_only_direct_dependencies": 0,
"allow_list": [
"third/module"
]
}
}
}
This means that this update strategy will create a pull request for you in these scenarios:
vendor/package1
).third/module
.But not if there is an update available for another indirect dependency without it also being an update available for a direct dependency.
name: always_update_all
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"always_update_all": 0
}
}
}
Indicate if you always want violinist to update all packages (simply the command composer update
with no arguments) every time it runs.
This is probably most useful if you have not so many dependencies, or if you are replacing a manual workflow that involves running composer update
on a regular basis. If you are using this option, only one pull request will be created by violinist, and it will contain the updates that would happen if you were running composer update
. So this option updates all of your dependencies, all of the time.
Note! This will not change any of your constraints. So strictly speaking, it will update all of your dependencies that has an update and where an update is allowed within the constraint.
Note! This option is incompatible with allow list and block list. Those lists are intended to limit the list of updates being attempted (that is, which commands are being run). With the option
always_update_all
you have no such control over which packages are updated. It’s simply all of them.
Let’s say your project looks like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "~1.0.0",
"othervendor/otherpackage": "^2.0.7",
"// ...and a dozen more...": 1
}
}
And then, maybe you don’t want one pull request per dependency. You simply want to update everything from time to time. Like you would do composer update
.
To change the behavior of violinist to only run composer update
with no arguments, and in one single merge request, you can do this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package1": "~1.0.0",
"othervendor/otherpackage": "^2.0.7",
"// ...and a dozen more...": 1
},
"extra": {
"violinist": {
"always_update_all": 1
}
}
}
This means that this update strategy will create a pull request for you in all of these scenarios:
vendor/package1
and there is a new version of vendor/package1
.vendor/package1
which in turn requires vendor/package2
, and there is no new version of vendor/package1
, but there is a new version of vendor/package2
.vendor/package1
which in turn requires vendor/package2
which in turn requires vendor/package3
, and there are no new versions for vendor/package1
or vendor/package2
, but there is a new version of vendor/package3
.Either way, if there were packages updated, they will all be bundled in the same merge request, and not in separate merge requests per package.
This feature is only available on the agency and enterprise plans. However, if the project in question is open-source, it’s available regardless of plan.
name: assignees
type: array
default: []
{
"name": "company/project",
"extra": {
"violinist": {
"assignees": []
}
}
}
An array of assignees that this project will use as the default assignee for new pull requests.
Note! The value of this option depends on your VCS provider. For github this will be an array of usernames. For gitlab the array should consist of user IDs. You can find your user id by visiting https://gitlab.com/api/v4/users?username=YOUR_USERNAME where YOUR_USERNAME is your gitlab username. (reference: https://forum.gitlab.com/t/where-is-my-user-id-in-gitlab-com/7912)
If you are using self hosted gitlab, change the domain accordingly.
Another difference is that gitlab only accepts one assignee per pull request. So while it should still be an array, if it contains more than one item, only the first user id will be assigned.
If you are using Bitbucket, then a limitation will be that you cannot assign the same user you have authenticated Violinist with. For example, if you logged in to Violinist using the username
user123
, then the value of assignees can not beuser123
as bitbucket does not allow this.
If you have a large team and want some people to get explicitly assigned (and probably by extension notified) per project, this is the setting to use. You can assign several users if you are using Github, but only one user if you are using Gitlab.
Say you wanted to assign the user my-review-user
for all pull requests created on the project company/project
. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project"
}
To make Violinist assign my-review-user
to all of the pull requests created, simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"assignees": [
"my-review-user"
]
}
}
}
Note! The above example is for github. For gitlab you would use a user id (see above).
name: automerge
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"automerge": 0
}
}
}
Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled.
Note! This option currently does not work with Bitbucket.
If you want even less work with your dependency updates, you might want violinist to also enable automerge on the pull/merge requests it opens. This way your dependencies will be truly automatically updated and merged once your tests pass!
If you want all pull/merge requests coming from violinist to have automerge enabled, and automatically get merged once your tests pass, you can specify that like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"automerge": 1
}
}
}
name: automerge_security
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"automerge_security": 0
}
}
}
Indicate whether or not you want pull/merge requests created by violinist to have the automerge option enabled when the update is a security update.
Note! This option currently does not work with Bitbucket.
Note! This option only overrides the automerge option if the update is a security update. If
automerge_security
is set to0
, butautomerge
is set to1
, then automerge will be enabled.
If you want even less work with your (security) dependency updates, you might want violinist to also enable automerge on the pull/merge requests it opens, when the update is a security update. This way your dependencies will be truly automatically updated and merged once your tests pass!
If you want all security related pull/merge requests coming from violinist to have automerge enabled, and automatically get merged once your tests pass, you can specify that like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"automerge_security": 1
}
}
}
Deprecated! Use blocklist instead
name: blocklist
type: array
default: []
{
"name": "company/project",
"extra": {
"violinist": {
"blocklist": []
}
}
}
An array of packages to always ignore while running updates with Violinist. Defaults to nothing.
Note! This option has no effect if used in combination with always_update_all.
Some times a version of your package comes out that will never be compatible with your codebase. Some times this means you have to do some refactoring, but you only have time to do so some time in the future. Some times this makes you annoyed that Violinist is continiously trying to update that package, even if you know it will fail. This could be an example of when you want to add a project to the block list.
If you want to add a project to the block list, you can add some extra information into your composer.json.
Say you wanted to add the project vendor/package
to the block list. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0"
}
}
To make Violinist stop trying to update vendor/package
you simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0"
},
"extra": {
"violinist": {
"blocklist": [
"vendor/package"
]
}
}
}
You can also use wildcards in your block list. Examples could be vendor/*
or vendor/prefix_*
.
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0"
},
"extra": {
"violinist": {
"blocklist": [
"vendor/*",
"vendor/prefix_*"
]
}
}
}
name: branch_prefix
type: string
default: ""
{
"name": "company/project",
"extra": {
"violinist": {
"branch_prefix": ""
}
}
}
A string representing a prefix that will be prepended before the default violinist branch name.
By default, violinist will create merge requests from a branch following a specific naming scheme. An update that updates psr/log from 1.0.0 to 1.1.4 would for example have a branch named psrlog100114
.
If you want to create some logic in your CI/CD system with regards to violinist, it can be practical to have all merge requests follow a prefix pattern. So then this option comes in handy.
Say you wanted to have all merge requests to follow the following pattern (same example update as above): violinist-prefix/psrlog100114
If you want to end your prefix with a special character. Say a slash (as above) or a dash. Please note that you have to specify the entire prefix string, including said last character.
Then you would add the following configuration (please note the last character is the slash in the prefix):
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"branch_prefix": "violinist-prefix/"
}
}
}
name: bundled_packages
type: object
default: {}
{
"name": "company/project",
"extra": {
"violinist": {
"bundled_packages": {}
}
}
}
An array of packages to bundle with other packages, keyed by the main package.
Quite often you probably want to also avoid getting pull requests for the packages you are bundling. To do this, you probably want to use a block list the packages in question.
Some times you depend on packages that are typically released in new versions at the same time. For example symfony packages. So instead of getting one pull request per symfony package your project depends on, you can get one pull request with all of them, bundled together with the update of one package.
This is even better when coupled with a block list of projects, so you just skip those bundled packages all together.
If you want to bundle some projects, you can add some extra information into your composer.json.
Say your project depends on both symfony/dom-crawler
and symfony/yaml
. And you want to get them both updated in one pull request, bundled with symfony/dom-crawler
. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"symfony/dom-crawler": "^3.4",
"symfony/yaml": "^3.4"
}
}
To make Violinist update them both together, you would do something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"symfony/dom-crawler": "^3.4",
"symfony/yaml": "^3.4"
},
"extra": {
"violinist": {
"bundled_packages": {
"symfony/dom-crawler": [
"symfony/yaml"
]
}
}
}
}
With the configuration above, when a new release is released for symfony/dom-crawler and symfony/yaml (which usually are released at the same time) you will get 2 pull requests. One pull request will update symfony/dom-crawler, bundled with symfony/yaml. The other one will update symfony/yaml. This is probably not what you want. You probably want to have just the one pull request for symfony/dom-crawler where symfony/yaml is already updated, and not get individual pull requests for symfony/yaml. To achieve this, you need to also add symfony/yaml to the block list. Like so:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"symfony/dom-crawler": "^3.4",
"symfony/yaml": "^3.4"
},
"extra": {
"violinist": {
"bundled_packages": {
"symfony/dom-crawler": [
"symfony/yaml"
]
},
"blocklist": [
"symfony/yaml"
]
}
}
}
Quite often when you are creating Drupal projects with composer, you will have several packages that are generated for the same core version.
The most common example of this is the package drupal/core-composer-scaffold
.
With the default violinist configuration you would get 2 merge requests when a new core version comes out. One for drupal/core-recommended
, and one for drupal/core-composer-scaffold
. This feels both tedious and unnecessary, since they kind of belong together, and are always released at the same time. So to skip the merge request for drupal/core-composer-scaffold
and instead get this bundled with drupal/core-recommended
you would add the following configuration to your composer.json
:
{
"name": "company/drupal-project",
"description": "My awesome Drupal project",
"require": {
"drupal/core-composer-scaffold": "^9.2.0",
"drupal/core-recommended": "^9.2.0"
},
"extra": {
"violinist": {
"bundled_packages": {
"drupal/core-recommended": [
"drupal/core-composer-scaffold"
]
},
"blocklist": [
"drupal/core-composer-scaffold"
]
}
}
}
If your project also uses drupal/core-project-message
and/or drupal/core-dev
you might want to add these as well.
name: check_only_direct_dependencies
type: int
default: 1
{
"name": "company/project",
"extra": {
"violinist": {
"check_only_direct_dependencies": 1
}
}
}
Indicate whether you want violinist to check only direct dependencies, or all dependencies.
Note! If you are looking for a way to get dependency updates of your direct dependencies, even if the direct dependency does not have a new version, then you probably want the option allow_update_indirect_with_direct. The difference being, with the option
allow_update_indirect_with_direct
you get one pull request per direct dependency. But with this option (check_only_direct_dependencies
set to 0) you get one pull request per package you have installed in your project, regardless of the package being directly required or not.
By default, violinist will only try to update packages you are directly dependent on. This means that if you are dependent on the package asm89/stack-cors
, your project will be indirectly dependent on for example symfony/http-foundation
. What that also means though, is that by default only pull requests to update the package asm89/stack-cors
will be created. For many projects, this is what is desired. However, the frequency of releases to these packages can vary a lot. For example, between 2 versions of asm89/stack-cors
there could theoretically be 10 versions of symfony/http-foundation
. Some then find it surprising that even if they are merging all of the pull requests from violinist, running composer update
still updates some packages for them. This is the reason.
Note! This option will update all dependencies in your lock file. This can potentially mean A LOT of pull requests. Therefore this option is best combined with either a block list or an allow list
Note! This option has no effect if you have set
always_update_all
to 1.
Note! This option has no effect if you have set
allow_update_indirect_with_direct
to 1.
Maybe you have a project that depend on a “meta-package” for your company, that in turn will download all of the dependencies of your framework of choice. This can be very convenient for making sure projects are similar, company-wide. However, your meta-package might not get new updates very often, so the indirect dependencies of your project (that is the dependencies of your “meta-package”) might become out of date. Or even cause you to miss a security update. Then let’s configure our project to get all updates for all dependencies.
{
"name": "company/project",
"description": "My awesome project",
"require": {
"company/package-with-symfony-dependencies-declared": "~1.0.0",
},
"extra": {
"violinist": {
"check_only_direct_dependencies": 0
}
}
}
This way, there will be pull requests created for all of the packages, direct or indirect. And dependencies will therefore be kept up to date, regardless of the meta-package company/package-with-symfony-dependencies-declared
getting a new version or not.
Note! Again, this will potentially create A LOT of pull requests. You probably want to combine this option with either a block list or an allow list. Or maybe with security_updates_only. Or maybe you might be looking for the option allow_update_indirect_with_direct
name: commit_message_convention
type: string
default: ""
{
"name": "company/project",
"extra": {
"violinist": {
"commit_message_convention": ""
}
}
}
For Violinist to use a commit message convention or not.
Violinist has support for using the Conventional Commits commit convention on its commit messages. To use this, set this option to the value conventional
. By default it will use no convention, which is the same as settings this value to none
.
If you want that Violinist commit messages follow the Conventional Commit, set the value to conventional
.
{
"name": "company/project",
"extra": {
"violinist": {
"commit_message_convention": "conventional"
}
}
}
This configuration will allow Violinist to push commit messages like:
build(dev): Update symfony/flex from v1.14.0 to v1.14.1
If you don’t want to have formatted commit messages, set it to none
or leave it blank.
{
"name": "company/project",
"extra": {
"violinist": {
"commit_message_convention": "none"
}
}
}
This will make Violinist not format its commit messages with any convention. An example message would be:
Update symfony/flex
name: default_branch
type: string
default: ''
{
"name": "company/project",
"extra": {
"violinist": {
"default_branch": ""
}
}
}
Indicate what branch you want the Violinist pull requests created against.
Different projects uses different workflows for their branches. For example, your default branch in your VCS provider might be your production branch (for example main
) while you want the pull requests to be created towards a development branch (for example develop
). By default, Violinist will use the default branch for the repository to create the pull requests, but if you want the base branch to differ from this setting, you want to use the default_branch
option.
If a project uses the main
branch as the default branch, and you want the pull requests to be based on the branch develop
, you might want to configure your project like so:
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"default_branch": "develop"
}
}
}
If you do not enter anything in this field, leaving the default value for it in there (""
- an empty string) the project will use the settings from the project repository. In the example above that would mean the branch main
.
This feature is only available on the agency and enterprise plans.
name: labels
type: array
default: []
{
"name": "company/project",
"extra": {
"violinist": {
"labels": []
}
}
}
An array of labels that should be added to the merge request.
Note! This option is not supported for Bitbucket, as Bitbucket does not support labels for their pull requests.
If you need to label the merge requests coming from violinist, for example for sorting them or even run logic in your CI pipeline, this option is probably what you want.
Say you wanted to label all pull requests coming from violinist with the label dependencies
. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project"
}
To make Violinist add the label dependencies
to all pull requests created, simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"labels": [
"dependencies"
]
}
}
}
This feature is only available on the agency and enterprise plans.
name: labels_security
type: array
default: []
{
"name": "company/project",
"extra": {
"violinist": {
"labels_security": []
}
}
}
An array of labels that should be added to the merge request, if the merge request is for a security update.
Note! This option is not supported for Bitbucket, as Bitbucket does not support labels for their pull requests.
If you need to label the merge requests coming from violinist that are security updates, for example for sorting them or even run logic in your CI pipeline, this option is probably what you want.
Note! Security labels will be added in addition to any labels you have configured with the option
labels
.
Say you wanted to label all security related pull requests coming from violinist with the label security asap
. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project"
}
To make Violinist add the label security asap
to all of the pull requests created that are security updates, simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"extra": {
"violinist": {
"labels_security": [
"security asap"
]
}
}
}
name: number_of_concurrent_updates
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"number_of_concurrent_updates": 0
}
}
}
Indicate how many open pull requests you want at a time.
If you have a whole range of build steps and environments for a project per branch, having a bunch of branches come in from Violinist might clog up your build pipeline or spin up many servers. If this is the case, and you want to throttle the pull requests Violinist keeps open, then this option is for you.
If you have a large project, some times the number of dependencies that are out of date could be many, especially when starting Violinist monitoring for the first time. And maybe you are creating QA enviroments for all your branches, or maybe your branches trigger build steps that take a long time to complete. So you want to throttle Violinist somehow. Then this option is for you. So if you wanted to limit the number of open pull requests to 5
, for example, then you would change your composer.json to look something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"number_of_concurrent_updates": 5
}
}
}
This way, the number of open pull requests will not pass 5 at any point. This will be true, even if you decide to change other configuration options, such as one_pull_request_per_package
for example, so it might be the case that you have to close some pull requests manually to achieve the desired result.
name: one_pull_request_per_package
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"one_pull_request_per_package": 0
}
}
}
Indicate whether you want one pull request per package or not.
Some packages update more often than you do maintenance on your project. If this is the case, you might find you have 4 pull requests for the version 8.0.2 through 8.0.5 of a certain package. This would in turn end up with you closing 3 pull requests, and merging one. If this is the case, maybe you want the option one_pull_request_per_package
, so you only have one pull request for that package, that keeps itself up to date.
If a package is out of date, and a new version comes out, the default behaviour of Violinist would be to create a new pull request for this version. But say you are not very active in maintaining your project, and you just want the one pull request to stay up to date. Say you want to come to your repo and see the pull request “Update vendor/package” instead of 4 pull requests with the titles “Update vendor/package to version x.x.x”. You simply go ahead and change this option to 1.
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"one_pull_request_per_package": 1
}
}
}
This way, the same pull request will stay up to date, when the next version comes out. Basically, violinist will force-push to the same branch for each new version, until you merge the update for the package, or the pull request becomes outdated by you updating the package manually.
name: run_scripts
type: int
default: 1
{
"name": "company/project",
"extra": {
"violinist": {
"run_scripts": 1
}
}
}
Indicate if you want to run scripts as part of your update commands. Or rather if you want to avoid running scripts.
This translates to using the --no-scripts
option in composer.
Some times you have projects that do magic things as part of their installation or update commands. For example creating databases or clearing Redis cache. If your project already has this stablished, you might want to avoid using this in violinist, as this would crash the update, meaning you get no updates.
Say you wanted to disable running scripts on your project for violinist, since it keeps crashing. You would go ahead and edit your composer.json as follows:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"run_scripts": 0
}
}
}
name: security_updates_only
type: int
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"security_updates_only": 0
}
}
}
Only update security updates to dependencies.
If you are only interested in getting automated pull requests for security updates to your dependencies, this option will do that for you.
Say you have a project with a lot of updates coming in all the time, but you are only interested in getting security updates through violinist. Then you would change the option security_updates_only
to 1. So in practice, change composer.json to look something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"security_updates_only": 1
}
}
}
This way, violinist will only send pull requests if a security updates is released of the package vendor/package
. For a regular update, no pull request is created.
name: timeframe_disallowed
type: string
default: 0
{
"name": "company/project",
"extra": {
"violinist": {
"timeframe_disallowed": 0
}
}
}
Indicate what timeframe the updater are allowed and disallowed to run.
By default, violinist will try to run updates all of the time. When a new package is released, or when it is time to rebase the existing pull requests. If you are actively working on a project during work hours, this can be either annoying or impractical. For example, it could clog up the CI pipeline if you have many projects monitored. So maybe you want to restrict the updater to run in a certain timeframe, so these pull requests and rebased branches can run when they are not getting in your way? If that is the case, you probably want the option timeframe_disallowed.
If you want to combine this with your local time, you want to use the option timezone
Say you want to only update the project with Violinist outside working hours. For example not inside the timeframe 6AM to 6PM (06:00 - 18:00). And say your composer.json looks like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
}
}
To make Violinist stop trying to update during working hours. Then you would specify a timeframe like so:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"timeframe_disallowed": "06:00-18:00"
}
}
}
name: timezone
type: string
default: +0000
{
"name": "company/project",
"extra": {
"violinist": {
"timezone": "+0000"
}
}
}
Indicate what timezone to use for the option timeframe_disallowed.
It would not help much to restrict the timeframe for the updates to be run, unless you could also say what timezone you were talking about. This is what the timezone option is for.
Say you want to only update the project with Violinist outside working hours, and you are located in the timezone PDT. By default, specifying a timeframe would use the UTC timezone, so to avoid having to convert the time to your timezone, you could specify this in your composer.json. So say your project, including timeframe_disallowed, had the following composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"extra": {
"violinist": {
"timeframe_disallowed": "06:00-18:00"
}
}
}
To make Violinist start using your timezone, you would add something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"timeframe_disallowed": "06:00-18:00",
"timezone": "-0700"
}
}
}
You can also use one of the predefined PHP timezones:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"timeframe_disallowed": "06:00-18:00",
"timezone": "America/Los_Angeles"
}
}
}
name: update_dev_dependencies
type: int
default: 1
{
"name": "company/project",
"extra": {
"violinist": {
"update_dev_dependencies": 1
}
}
}
Indicate whether or not you want Violinist to also update your dev dependencies. The default behavior is to also update these.
If you have a project where you for some reason do not want to update your dev dependencies, you can use this option.
Say you wanted to avoid updating all of your dev dependencies. And say your composer.json looked something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"require-dev": {
"vendor/dev-package": "*",
"vendor/dev-package2": "*",
"vendor/dev-package3": "*"
}
}
To make Violinist stop updating your dev dependencies, you simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
},
"require-dev": {
"vendor/dev-package": "*",
"vendor/dev-package2": "*",
"vendor/dev-package3": "*"
},
"extra": {
"violinist": {
"update_dev_dependencies": 0
}
}
}
name: update_with_dependencies
type: int
default: 1
{
"name": "company/project",
"extra": {
"violinist": {
"update_with_dependencies": 1
}
}
}
Indicate whether or not we update a package using the --with-dependencies
flag for composer. Defaults to 1 (true).
When you update a package that also depend on other packages, which probably in turn are described as dependencies with semantic versioning, you might want to update to the newest version of the depended-upon packages as well, since these are compatible and will include bug fixes and improvements for you, in a compatible way. If you do not want this, then this configuration option is what you are after.
Say you depend on the project vendor/package
in range ~1.0.0
. And say the latest version is 1.1.0. And say you vendor/package
depends on vendor2/package2
in the range ~2.0.0
. And say that in your last upgrade of vendor/package
you got version 2.0.1
of the package vendor2/package2
, and now the version 2.0.2
is available. By default, Violinist will then also upgrade package vendor2/package2
for you. But maybe this is not what you want, since you in another part of your codebase actually rely on a bug that exists in version 2.0.1
. And say your composer.json looks something like this:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "~1.0.0",
}
}
To make Violinist stop trying to update vendor2/package2
when updating your direct dependency vendor/package
(and similar for all other packages) you simply add the following to your composer.json:
{
"name": "company/project",
"description": "My awesome project",
"require": {
"vendor/package": "^1.4.0",
},
"extra": {
"violinist": {
"update_with_dependencies": 0
}
}
}