yaml¶
This rule checks YAML syntax by using yamllint library but with a
specific default configuration, one that is
compatible with both, our internal reformatter (--fix
) and also prettier.
You can disable YAML syntax violations by adding yaml
to the skip_list
in
your Ansible-lint configuration as follows:
For more fine-grained control, disable violations for specific rules using tag
identifiers in the yaml[yamllint_rule]
format as follows:
If you want Ansible-lint to report YAML syntax violations as warnings, and not
fatal errors, add tag identifiers to the warn_list
in your configuration, for
example:
Warning
You cannot use tags: [skip_ansible_lint]
to disable this rule but you can
use yamllint magic comments for tuning it.
See the list of yamllint rules for more information.
Some of the detailed error codes that you might see are:
yaml[brackets]
- too few spaces inside empty brackets, or too many spaces inside bracketsyaml[colons]
- too many spaces before colon, or too many spaces after colonyaml[commas]
- too many spaces before comma, or too few spaces after commayaml[comments-indentation]
- Comment not indented like contentyaml[comments]
- Too few spaces before comment, or Missing starting space in commentyaml[document-start]
- missing document start "---" or found forbidden document start "---"yaml[empty-lines]
- too many blank lines (...> ...)yaml[indentation]
- Wrong indentation: expected ... but found ...yaml[key-duplicates]
- Duplication of key "..." in mappingyaml[line-length]
- Line too long (... > ... characters)yaml[new-line-at-end-of-file]
- No new line character at the end of fileyaml[octal-values]
: forbidden implicit or explicit octal valueyaml[syntax]
- YAML syntax is brokenyaml[trailing-spaces]
- Spaces are found at the end of linesyaml[truthy]
- Truthy value should be one of ...
Octals¶
As YAML specification regarding octal values changed at least 3 times in 1.1, 1.2.0 and 1.2.2 we now require users to always add quotes around octal values, so the YAML loaders will all load them as strings, providing a consistent behavior. This is also safer as JSON does not support octal values either.
By default, yamllint does not check for octals but our custom default ruleset
for it does check these. If for some reason, you do not want to follow our
defaults, you can create a .yamllint
file in your project and this will take
precedence over our defaults.
Additional Information for Multiline Strings¶
Adhering to yaml[line-length] rule, for writing multiline strings we recommend using Block Style Indicator: literal style indicated by a pipe (|) or folded style indicated by a right angle bracket (>), instead of escaping the newlines with backslashes. Reference guide for writing multiple line strings in yaml.
Problematic code¶
# Missing YAML document start.
foo: 0777 # <-- yaml[octal-values]
foo2: 0o777 # <-- yaml[octal-values]
foo2: ... # <-- yaml[key-duplicates]
bar: ... # <-- yaml[comments-indentation]
Correct code¶
---
foo: "0777" # <-- Explicitly quoting octal is less risky.
foo2: "0o777" # <-- Explicitly quoting octal is less risky.
bar: ... # Correct comment indentation.
Yamllint configuration¶
If you decide to add a custom yamllint config to your project, ansible-lint might refuse to run if it detects that some of your options are incompatible and ask you to correct them. When this happens, you will see a message like the one below:
CRITICAL Found incompatible custom yamllint configuration (.yamllint), please either remove the file or edit it to comply with:
- comments.min-spaces-from-content must be 1
- braces.min-spaces-inside must be 0
- braces.max-spaces-inside must be 1
- octal-values.forbid-implicit-octal must be true
- octal-values.forbid-explicit-octal must be true
Read https://ansible.readthedocs.io/projects/lint/rules/yaml/ for more details regarding why we have these requirements.
Warning
Auto-fix functionality will change inline comment indentation to one character instead of two, which is the default of yamllint. The reason for this decision was to keep reformatting compatibility with prettier, which is the most popular reformatter.
There is no need to create this yamllint config file, but if you also run yamllint yourself, you might want to create it to make it behave the same way as ansible-lint.
Below you can find the default yamllint configuration that our linter will use when there is no custom file present.
extends: default
rules:
comments:
# https://github.com/prettier/prettier/issues/6780
min-spaces-from-content: 1
# https://github.com/adrienverge/yamllint/issues/384
comments-indentation: false
document-start: disable
# 160 chars was the default used by old E204 rule, but
# you can easily change it or disable in your .yamllint file.
line-length:
max: 160
# We are adding an extra space inside braces as that's how prettier does it
# and we are trying not to fight other linters.
braces:
min-spaces-inside: 0 # yamllint defaults to 0
max-spaces-inside: 1 # yamllint defaults to 0
# key-duplicates:
# forbid-duplicated-merge-keys: true # not enabled by default
octal-values:
forbid-implicit-octal: true # yamllint defaults to false
forbid-explicit-octal: true # yamllint defaults to false
# quoted-strings:
# quote-type: double
# required: only-when-needed