GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

cloudflare/pint

Public

mirrored from https://github.com/cloudflare/pintAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
v0.15.0

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

pint/docs

docs/configuration.md

277lines · modecode

RawDownload
Latest commit unavailable.
1---
2layout: default
3title: Configuration
4parent: Documentation
5nav_order: 2
6---
7
8# Configuration syntax
9
10## Table of contents
11{: .no_toc .text-delta }
12
131. TOC
14{:toc}
15
16## Regexp matchers
17
18All regexp patterns use [Go regexp](https://pkg.go.dev/regexp) module and are fully anchored.
19This means that when you pass `.*` regexp expression internally it will be represented as
20`^.*$`, where `^` indicates beginning of a string and `$` is the end of string.
21This follow [PromQL behavior](https://prometheus.io/docs/prometheus/latest/querying/basics/)
22for consistency with Prometheus.
23If you have a string `alice bob john` and you want to match a substring `bob`, then be sure to use
24`.*bob.*`.
25
26When using regexp matcher in checks configuration you can reference alerting and recording rule
27fields in the regexp using [Go text/template](https://pkg.go.dev/text/template) syntax.
28Rule fields are exposed as:
29
30- `$alert` - rule `alert` field
31- `$record` - rule `record` field
32- `$expr` - rule `expr` field
33- `$for` - rule `for` field
34- `$labels` - rule `labels` map, individual labels can be accessed as `$labels.foo`
35- `$annotations` - rule `annotations` map, individual annotations can be accessed as `$annotations.foo`
36
37Accessing a field that's not present in the rule will return an empty string.
38
39## CI
40
41Configure continuous integration environments.
42
43Syntax:
44
45```js
46ci {
47 include = [ "(.*)", ... ]
48 maxCommits = 20
49 baseBranch = "master"
50}
51```
52
53- `include` - list of file patterns to check when running checks. Only files
54 matching those regexp rules will be checked, other modified files will be ignored.
55- `maxCommits` - by default pint will try to find all commits on the current branch,
56 this requires full git history to be present, if we have a shallow clone this
57 might fail to find only current branch commits and give us a huge list.
58 If the number of commits returned by branch discovery is more than `maxCommits`
59 then pint will fail to run.
60- `baseBranch` - base branch to compare `HEAD` commit with when calculating the list
61 of commits to check.
62
63## Repository
64
65Configure supported code hosting repository, used for reporting PR checks from CI
66back to the repository, to be displayed in the PR UI.
67Currently it only supports [BitBucket](https://bitbucket.org/) and [GitHub](https://github.com/).
68
69**NOTE**: BitBucket integration requires `BITBUCKET_AUTH_TOKEN` environment variable
70to be set. It should contain a personal access token used to authenticate with the API.
71
72**NOTE**: GitHub integration requires `GITHUB_AUTH_TOKEN` environment variable
73to be set to a personal access key that can access your repository. Also, `GITHUB_PULL_REQUEST_NUMBER`
74environment variable needs to point to the pull request number which will be used whilst
75submitting comments.
76
77Syntax:
78
79```js
80repository {
81 bitbucket {
82 uri = "https://..."
83 timeout = "30s"
84 project = "..."
85 repository = "..."
86 }
87}
88```
89
90- `bitbucket:uri` - base URI of this repository, will be used for HTTP
91 requests to the BitBucket API.
92- `bitbucket:timeout` - timeout to be used for API requests.
93- `bitbucket:project` - name of the BitBucket project for this repository.
94- `bitbucket:repository` - name of the BitBucket repository.
95
96```js
97repository {
98 github {
99 baseuri = "https://..."
100 uploaduri = "https://..."
101 timeout = "30s"
102 owner = "..."
103 repo = "..."
104 }
105}
106```
107
108- `github:baseuri` - base URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
109- `github:uploaduri` - upload URI of GitHub or GitHub enterprise, will be used for HTTP requests to the GitHub API.
110
111If `github:baseuri` _or_ `github:uploaduri` are not specified then [GitHub](https://github.com) will be used.
112
113- `github:timeout` - timeout to be used for API requests;
114- `github:owner` - name of the GitHub owner i.e. the first part that comes before the repository's name in the URI;
115- `github:repo` - name of the GitHub repository (e.g. `monitoring`).
116
117## Prometheus servers
118
119Some checks work by querying a running Prometheus instance to verify if
120metrics used in rules are present. If you want to use those checks then you
121first need to define one or more Prometheus servers.
122
123Syntax:
124
125```js
126prometheus "$name" {
127 uri = "https://..."
128 failover = ["https://...", ...]
129 timeout = "60s"
130 required = true|false
131 paths = ["...", ...]
132}
133```
134
135- `$name` - each defined server should have a unique name that can be used in check
136 definitions.
137- `uri` - base URI of this Prometheus server, used for API requests and queries.
138- `failover` - list of URIs to try (in order they are specified) if `uri` doesn't respond
139 to requests or returns an error. This allows to configure failover Prometheus servers
140 to avoid CI failures in case main Prometheus server is unreachable.
141 Failover URIs are not used if Prometheus returns an error caused by the query, like
142 `many-to-many matching not allowed`.
143 It's highly recommended that all URIs point to Prometheus servers with identical
144 configuration, otherwise pint checks might return unreliable results and potential
145 false positives.
146- `timeout` - timeout to be used for API requests.
147- `required` - decides how pint will report errors if it's unable to get a valid response
148 from this Prometheus server. If `required` is `true` and all API calls to this Prometheus
149 fail pint will report those as `bug` level problem. If it's set to `false` pint will
150 report those with `warning` level.
151 Default value for `required` is `false`. Set it to `true` if you want to hard fail
152 in case of remote Prometheus issues. Note that setting it to `true` might block
153 PRs when running `pint ci` until pint is able to talk to Prometheus again.
154- `paths` - optional path filter, if specified only paths matching one of listed regexp
155 patterns will use this Prometheus server for checks.
156
157Example:
158
159```js
160prometheus "prod" {
161 uri = "https://prometheus-prod.example.com"
162 timeout = "60s"
163}
164
165prometheus "dev" {
166 uri = "https://prometheus-dev.example.com"
167 timeout = "30s"
168 paths = [ "alerts/test/.*" ]
169}
170```
171
172## Matching rules to checks
173
174Most checks, except basic syntax verification, requires some configuration to decide
175which checks to run against which files and rules.
176
177Syntax:
178
179```js
180rule {
181 match {
182 path = "(.+)"
183 name = "(.+)"
184 kind = "alerting|recording"
185 command = "ci|lint|watch"
186 annotation "(.*)" {
187 value = "(.*)"
188 }
189 label "(.*)" {
190 value = "(.*)"
191 }
192 for = "..."
193 }
194 match { ... }
195 match { ... }
196 ignore {
197 path = "(.+)"
198 name = "(.+)"
199 kind = "alerting|recording"
200 command = "ci|lint|watch"
201 annotation "(.*)" {
202 value = "(.*)"
203 }
204 label "(.*)" {
205 value = "(.*)"
206 }
207 for = "..."
208 }
209 ignore { ... }
210 ignore { ... }
211
212 [ check definition ]
213 ...
214 [ check definition ]
215}
216```
217
218- `match:path` - only files matching this pattern will be checked by this rule
219- `match:name` - only rules with names (`record` for recording rules and `alert` for alerting
220 rules) matching this pattern will be checked rule
221- `match:kind` - optional rule type filter, only rule of this type will be checked
222- `match:command` - optional command type filter, this allows to include or ignore rules
223 based on the command pint is run with `pint ci`, `pint lint` or `pint watch`.
224- `match:annotation` - optional annotation filter, only alert rules with at least one
225 annotation matching this pattern will be checked by this rule.
226- `match:label` - optional annotation filter, only rules with at least one label
227 matching this pattern will be checked by this rule. For recording rules only static
228 labels set on the recording rule are considered.
229- `match:for` - optional alerting rule `for` filter. If set only alerting rules with `for`
230 field present and matching provided value will be checked by this rule. Recording rules
231 will never match it as they don't have `for` field.
232 Syntax is `OP DURATION` where `OP` can be any of `=`, `!=`, `>`, `>=`, `<`, `<=`.
233- `ignore` - works exactly like `match` but does the opposite - any alerting or recording rule
234 matching all conditions defined on `ignore` will not be checked by this `rule` block.
235
236Note: both `match` and `ignore` require all defined filters to be satisfied to work.
237If multiple `match` and/or `ignore` rules are present any of them needs to match for the rule to
238be matched / ignored.
239
240Examples:
241
242```js
243rule {
244 match {
245 path = "rules/.*"
246 kind = "alerting"
247 label "severity" {
248 value = "(warning|critical)"
249 }
250 }
251 ignore {
252 command = "watch"
253 }
254 [ check applied only to severity="critical" and severity="warning" alerts in "ci" or "lint" command is run ]
255}
256```
257
258```js
259rule {
260 ignore {
261 command = "watch"
262 }
263 ignore {
264 command = "lint"
265 }
266 [ check applied unless "watch" or "lint" command is run ]
267}
268```
269
270```js
271rule {
272 match {
273 for = ">= 5m"
274 }
275 [ check applied only to alerting rules with "for" field value that is >= 5m ]
276}
277```
278