Skip to content

Commit 248254d

Browse files
jippijippi
committed
update README
1 parent 5fabf76 commit 248254d

File tree

1 file changed

+143
-76
lines changed

1 file changed

+143
-76
lines changed

‎README.md

+143-76
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,39 @@
77
>
88
> SCM engine can be run either as a regular CI job in your pipeline, or be triggered through the Webhook system, allowing for versatile and flexible deployments.
99
10+
- [Installation](#installation)
11+
- [Commands](#commands)
12+
- [`evaluate`](#evaluate)
13+
- [Configuration file](#configuration-file)
14+
- [Examples](#examples)
15+
- [`label` (list)](#label-list)
16+
- [`label.name`](#labelname)
17+
- [`label.script` (required)](#labelscript-required)
18+
- [`label.strategy` (optional)](#labelstrategy-optional)
19+
- [`label.strategy: conditional` use-cases](#labelstrategy-conditional-use-cases)
20+
- [`label.strategy: conditional` examples](#labelstrategy-conditional-examples)
21+
- [`label.strategy: generate` use-cases](#labelstrategy-generate-use-cases)
22+
- [`label.strategy: generate` examples](#labelstrategy-generate-examples)
23+
- [`label.color` (required)](#labelcolor-required)
24+
- [`label.description` (optional)](#labeldescription-optional)
25+
- [`label.priority` (optional)](#labelpriority-optional)
26+
- [`label.skip_if` (optional)](#labelskip_if-optional)
27+
- [Expr-lang information](#expr-lang-information)
28+
- [Attributes](#attributes)
29+
- [project](#project)
30+
- [project.labels](#projectlabels)
31+
- [group](#group)
32+
- [merge_request](#merge_request)
33+
- [merge_request.diff_stats](#merge_requestdiff_stats)
34+
- [merge_request.first_commit](#merge_requestfirst_commit)
35+
- [merge_request.last_commit](#merge_requestlast_commit)
36+
- [merge_request.labels](#merge_requestlabels)
37+
- [Functions](#functions)
38+
- [`merge_request.modified_files`](#merge_requestmodified_files)
39+
- [`duration`](#duration)
40+
- [`uniq`](#uniq)
41+
- [`filepath_dir`](#filepath_dir)
42+
1043
## Installation
1144

1245
TODO
@@ -84,11 +117,11 @@ These keys are shared between the `conditional` and `generate` label strategy. (
84117

85118
#### `label.name`
86119

87-
* When using `label.strategy: conditional`
120+
- When using `label.strategy: conditional`
88121

89122
**REQUIRED** The `name` of the label to create.
90123

91-
* When using `label.strategy: generate`
124+
- When using `label.strategy: generate`
92125

93126
**OMITTED** The `name` field must not be set when using the `generate` strategy.
94127

@@ -105,11 +138,11 @@ Depending on the `label.strategy` used, the behavior of the script changes, read
105138

106139
SCM Engine supports two strategies for managing labels, each changes the behavior of the `script`.
107140

108-
* `conditional` (default, if `type` key is omitted), where you provide the `name` of the label, and a `script` that returns a boolean for wether the label should be added to the Merge Request.
141+
- `conditional` (default, if `type` key is omitted), where you provide the `name` of the label, and a `script` that returns a boolean for wether the label should be added to the Merge Request.
109142

110143
The `script` must return a `boolean` value, where `true` mean `add the label` and `false` mean `remove the label`.
111144

112-
* `generate`, where your `script` generates the list of labels that should be added to the Merge Request.
145+
- `generate`, where your `script` generates the list of labels that should be added to the Merge Request.
113146

114147
The `script` must return a `list of strings`, where each label returned will be added to the Merge Request.
115148

@@ -152,11 +185,11 @@ label:
152185
script: merge_request.modified_files("*_test.go")
153186
```
154187

155-
###### `label.strategy: generate` use-cases
188+
##### `label.strategy: generate` use-cases
156189

157190
Use the `generate` strategy if you want to manage dynamic labels, for example, depending on the file structure within your project.
158191

159-
###### `label.strategy: generate` examples
192+
##### `label.strategy: generate` examples
160193

161194
> The `script` field is a [expr-lang](https://expr-lang.org/) expression, a safe, fast, and intuitive expression evaluator.
162195

@@ -232,82 +265,116 @@ The `skip_if` field must be a valid [Expr-lang](https://expr-lang.org/) expressi
232265
> Missing an attribute? The `pkg/scm/gitlab/context_*` files are what is used to query GitLab, adding the missing `field` to the right `struct` should make it accessible.
233266
> Please open an issue or Pull Request if something is missing.
234267

268+
> [!IMPORTANT]
269+
> _SCM Engine uses [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for fields instead of [`camelCase`](https://en.wikipedia.org/wiki/Camel_case)_
270+
235271
The following attributes are available in `script` fields.
236272

237273
They can be accessed exactly as shown in this list.
238274

239-
#### Project
275+
#### project
240276

241277
> [!NOTE]
242-
> See the GitLab GraphQL [`Project`](https://docs.gitlab.com/ee/api/graphql/reference/#project), [`Group`](https://docs.gitlab.com/ee/api/graphql/reference/#group), [`MergeRequest`](https://docs.gitlab.com/ee/api/graphql/reference/#mergerequest), [`Label`](https://docs.gitlab.com/ee/api/graphql/reference/#label), and [`Commit`](https://docs.gitlab.com/ee/api/graphql/reference/#commit) GraphQL resource for more details about the fields.
243-
>
244-
> _Note that we use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for fields instead of [`camelCase`](https://en.wikipedia.org/wiki/Camel_case)_
245-
246-
* `project.archived` (boolean)
247-
* `project.created_at` (time)
248-
* `project.description` (string)
249-
* `project.full_path` (string)
250-
* `project.id` (string)
251-
* `project.labels[].color` (string)
252-
* `project.labels[].description` (string)
253-
* `project.labels[].id` (string)
254-
* `project.labels[].title` (string)
255-
* `project.last_activity_at` (time)
256-
* `project.name_with_namespace` (string)
257-
* `project.name` (string)
258-
* `project.path` (string)
259-
* `project.topics[]` (array of string)
260-
* `project.updated_at` (time)
261-
* `project.visibility` (string)
262-
* `group.description` (string)
263-
* `group.id` (string)
264-
* `group.name` (string)
265-
* `merge_request.approvals_left` (int)
266-
* `merge_request.approvals_required` (int)
267-
* `merge_request.approved` (boolean)
268-
* `merge_request.auto_merge_enabled` (int)
269-
* `merge_request.auto_merge_strategy` (string)
270-
* `merge_request.conflicts` (bool)
271-
* `merge_request.created_at` (time)
272-
* `merge_request.description` (string)
273-
* `merge_request.diff_stats[].additions` (int)
274-
* `merge_request.diff_stats[].deletions` (int)
275-
* `merge_request.diff_stats[].path` (string)
276-
* `merge_request.diverged_from_target_branch` (bool)
277-
* `merge_request.draft` (boolean)
278-
* `merge_request.first_commit.author_email` (string)
279-
* `merge_request.first_commit.committed_date` (string)
280-
* `merge_request.id` (string)
281-
* `merge_request.iid` (string)
282-
* `merge_request.labels[].color` (string)
283-
* `merge_request.labels[].description` (string)
284-
* `merge_request.labels[].id` (string)
285-
* `merge_request.labels[].title` (string)
286-
* `merge_request.last_commit.author_email` (string)
287-
* `merge_request.last_commit.committed_date` (string)
288-
* `merge_request.merge_status_enum` (string)
289-
* `merge_request.mergeable` (boolean)
290-
* `merge_request.merged_at` (optional, time)
291-
* `merge_request.source_branch_exists` (boolean)
292-
* `merge_request.source_branch_protected` (boolean)
293-
* `merge_request.source_branch` (string)
294-
* `merge_request.squash_on_merge` (boolean)
295-
* `merge_request.squash` (boolean)
296-
* `merge_request.state` (string)
297-
* `merge_request.target_branch` (string)
298-
* `merge_request.target_branch_exists` (string)
299-
* `merge_request.time_between_first_and_last_commit` (duration) - SCM Engine -
300-
The `duration()` between the first and last commit in the Merge Request.
301-
* `merge_request.time_since_first_commit` (duration) - SCM Engine -
302-
The `duration()` between `now()` and the first commit in the Merge Request.
303-
* `merge_request.time_since_last_commit` (duration) - SCM Engine -
304-
The `duration()` between `now()` and the last commit in the Merge Request.
305-
* `merge_request.title` (string)
306-
* `merge_request.updated_at` (time)
278+
> See the [GitLab GraphQL `Project` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#project) for more details about the fields.
279+
280+
- `project.archived` (boolean)
281+
- `project.created_at` (time)
282+
- `project.description` (string)
283+
- `project.full_path` (string)
284+
- `project.id` (string)
285+
- `project.last_activity_at` (time)
286+
- `project.name_with_namespace` (string)
287+
- `project.name` (string)
288+
- `project.path` (string)
289+
- `project.topics[]` (array of string)
290+
- `project.updated_at` (time)
291+
- `project.visibility` (string)
292+
293+
#### project.labels
294+
295+
> [!NOTE]
296+
> See the [GitLab GraphQL `Label` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#label) for more details about the fields.
297+
298+
- `project.labels[].color` (string)
299+
- `project.labels[].description` (string)
300+
- `project.labels[].id` (string)
301+
- `project.labels[].title` (string)
302+
303+
#### group
304+
305+
> See the [GitLab GraphQL `Group` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#group) for more details about the fields.
306+
307+
- `group.description` (string)
308+
- `group.id` (string)
309+
- `group.name` (string)
310+
311+
#### merge_request
312+
313+
> See the [GitLab GraphQL `MergeRequest` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#mergerequest) for more details about the fields.
314+
315+
- `merge_request.approvals_left` (int)
316+
- `merge_request.approvals_required` (int)
317+
- `merge_request.approved` (boolean)
318+
- `merge_request.auto_merge_enabled` (int)
319+
- `merge_request.auto_merge_strategy` (string)
320+
- `merge_request.conflicts` (bool)
321+
- `merge_request.created_at` (time)
322+
- `merge_request.description` (string)
323+
- `merge_request.diverged_from_target_branch` (bool)
324+
- `merge_request.draft` (boolean)
325+
- `merge_request.id` (string)
326+
- `merge_request.iid` (string)
327+
- `merge_request.merge_status_enum` (string)
328+
- `merge_request.mergeable` (boolean)
329+
- `merge_request.merged_at` (optional, time)
330+
- `merge_request.source_branch_exists` (boolean)
331+
- `merge_request.source_branch_protected` (boolean)
332+
- `merge_request.source_branch` (string)
333+
- `merge_request.squash_on_merge` (boolean)
334+
- `merge_request.squash` (boolean)
335+
- `merge_request.state` (string)
336+
- `merge_request.target_branch_exists` (string)
337+
- `merge_request.target_branch` (string)
338+
- `merge_request.time_between_first_and_last_commit` (duration) - SCM Engine - The `duration()` between the first and last commit in the Merge Request.
339+
- `merge_request.time_since_first_commit` (duration) - SCM Engine - The `duration()` between `now()` and the first commit in the Merge Request.
340+
- `merge_request.time_since_last_commit` (duration) - SCM Engine - The `duration()` between `now()` and the last commit in the Merge Request.
341+
- `merge_request.title` (string)
342+
- `merge_request.updated_at` (time)
343+
344+
#### merge_request.diff_stats
345+
346+
> See the [GitLab GraphQL `DiffStats` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#diffstats) for more details about the fields.
347+
348+
- `merge_request.diff_stats[].additions` (int)
349+
- `merge_request.diff_stats[].deletions` (int)
350+
- `merge_request.diff_stats[].path` (string)
351+
352+
#### merge_request.first_commit
353+
354+
> See the [GitLab GraphQL `Commit` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#commit) for more details about the fields.
355+
356+
- `merge_request.first_commit.author_email` (string)
357+
- `merge_request.first_commit.committed_date` (string)
358+
359+
#### merge_request.last_commit
360+
361+
> See the [GitLab GraphQL `Commit` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#commit) for more details about the fields.
362+
363+
- `merge_request.last_commit.author_email` (string)
364+
- `merge_request.last_commit.committed_date` (string)
365+
366+
#### merge_request.labels
367+
368+
> See the [GitLab GraphQL `Label` GraphQL resource](https://docs.gitlab.com/ee/api/graphql/reference/#label) for more details about the fields.
369+
370+
- `merge_request.labels[].color` (string)
371+
- `merge_request.labels[].description` (string)
372+
- `merge_request.labels[].id` (string)
373+
- `merge_request.labels[].title` (string)
307374

308375
### Functions
309376

310-
### merge_request.modified_files(str...)
377+
#### `merge_request.modified_files`
311378

312379
Returns wether any of the provided files patterns have been modified in the Merge Request.
313380

@@ -317,7 +384,7 @@ The file patterns use the [`.gitignore` format](https://git-scm.com/docs/gitigno
317384
merge_request.modified_files("*.go", "docs/")
318385
```
319386

320-
#### duration(str)
387+
#### `duration`
321388

322389
Returns the [`time.Duration`](https://pkg.go.dev/time#Duration) value of the given string str.
323390

@@ -327,15 +394,15 @@ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d" and "w".
327394
duration("1h").Seconds() == 3600
328395
```
329396

330-
#### uniq(array)
397+
#### `uniq`
331398

332399
Returns a new array where all duplicate values has been removed.
333400

334401
```expr
335402
(["hello", "world", "world"] | uniq) == ["hello", "world"]
336403
```
337404

338-
#### filepath_dir(string)
405+
#### `filepath_dir`
339406

340407
`filepath_dir` returns all but the last element of path, typically the path's directory. After dropping the final element,
341408

0 commit comments

Comments
 (0)