1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# yaml
This rule checks YAML syntax by using [yamllint] library but with a
[specific default configuration](#yamllint-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:
```yaml
skip_list:
- yaml
```
For more fine-grained control, disable violations for specific rules using tag
identifiers in the `yaml[yamllint_rule]` format as follows:
```yaml
skip_list:
- yaml[trailing-spaces]
- yaml[indentation]
```
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:
```yaml
warn_list:
- yaml[document-start]
```
!!! warning
You cannot use `tags: [skip_ansible_lint]` to disable this rule but you can
use [yamllint magic comments](https://yamllint.readthedocs.io/en/stable/disable_with_comments.html#disabling-checks-for-all-or-part-of-the-file) for tuning it.
See the
[list of yamllint rules](https://yamllint.readthedocs.io/en/stable/rules.html)
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 brackets_
- `yaml[colons]` - _too many spaces before colon_, or _too many spaces after
colon_
- `yaml[commas]` - _too many spaces before comma_, or _too few spaces after
comma_
- `yaml[comments-indentation]` - _Comment not indented like content_
- `yaml[comments]` - _Too few spaces before comment_, or _Missing starting space
in comment_
- `yaml[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 mapping_
- `yaml[line-length]` - _Line too long (... > ... characters)_
- `yaml[new-line-at-end-of-file]` - _No new line character at the end of file_
- `yaml[octal-values]`: forbidden implicit or explicit [octal](#octals) value
- `yaml[syntax]` - YAML syntax is broken
- `yaml[trailing-spaces]` - Spaces are found at the end of lines
- `yaml[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
```yaml
# Missing YAML document start.
foo: 0777 # <-- yaml[octal-values]
foo2: 0o777 # <-- yaml[octal-values]
foo2: ... # <-- yaml[key-duplicates]
bar: ... # <-- yaml[comments-indentation]
```
## Correct code
```yaml
---
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](../autofix.md) 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.
```yaml title=".yamllint"
rules:
comments:
min-spaces-from-content: 1 # prettier compatibility
```
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.
```yaml
{!../src/ansiblelint/data/.yamllint!}
```
[1.1]: https://yaml.org/spec/1.1/
[1.2.0]: https://yaml.org/spec/1.2.0/
[1.2.2]: https://yaml.org/spec/1.2.2/
[yaml specification]: https://yaml.org/
[guide]:
https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics
[prettier]: https://prettier.io/
[yamllint]: https://yamllint.readthedocs.io/en/stable/
|
