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
154
|
---
stage: Verify
group: Pipeline Authoring
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# CI/CD YAML reference style guide **(FREE)**
The CI/CD YAML reference uses a standard style to make it easier to use and update.
The reference information should be kept as simple as possible, and expanded details
and examples documented in a separate page.
## YAML reference structure
Every YAML keyword must have its own section in the reference. The sections should
be nested so that the keywords follow a logical tree structure. For example:
```plaintext
### `artifacts`
#### `artifacts:name`
#### `artifacts:paths`
#### `artifacts:reports`
##### `artifacts:reports:dast`
##### `artifacts:reports:sast`
```
## YAML reference style
Each keyword entry in the reference should use the following style:
````markdown
### `keyword-name`
> Version information
Keyword description and main details.
**Keyword type**:
**Possible inputs**:
**Example of `keyword-name`**:
(optional) In this example...
(optional) **Additional details**:
- List of extra details.
(optional) **Related topics**:
- List of links to topics related to the keyword.
````
- ``### `keyword-name` ``: The keyword name must always be in backticks.
If it is a subkey of another keyword, write out all the keywords, with each separated
by `:`, for example: `artifacts:reports:dast`.
- ``> Version information``: The [version history details](../documentation/styleguide/index.md#version-text-in-the-version-history).
If the keyword is feature flagged, see the [feature flag documentation guide](../documentation/feature_flags.md)
as well.
- `Keyword description and main details.`: A simple description of the keyword, and
how to use it. Additional use cases and benefits should be added to a page outside
the reference document. Link to that document in this section.
- `**Keyword type**:`: Most keywords are defined at the job level, like `script`,
or at the pipeline level, like `stages`. Add the appropriate line:
- `**Keyword type**: Job keyword. You can use it only as part of a job.`
- `**Keyword type**: Pipeline keyword. You cannot use it as part of a job.`
If a keyword can be used at both the job and pipeline level, like `variables`,
explain it in detail instead of using the pre-written lines above.
- `**Possible inputs**:`: Explain in detail which inputs the keyword can accept.
You can add the details in a sentence, paragraph, or list.
- ``**Example of `keyword-name`**:``: An example configuration that uses the keyword.
Do not add extra keywords that are not required to understand the behavior.
- (optional) `In this example...`: If the example needs extra details,
add the clarification text below the example.
- (optional) `**Additional details**:` If there are any caveats or extra details you
want to document along with the keyword, add each one as a list item here.
- (optional) `**Related topics**:` If there are any other keywords or pages that
relate to this keyword, add these links as list items here.
### YAML reference style example
See the [`only:changes` / `except:changes`](../../ci/yaml/index.md#onlychanges--exceptchanges)
documentation for an example of the YAML reference style. The following example is a
shortened version of that documentation's Markdown:
````markdown
#### `only:changes` / `except:changes`
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4.
Use the `changes` keyword with `only` to run a job, or with `except` to skip a job,
when a Git push event modifies a file.
Use `changes` in pipelines with the following refs:
- `branches`
- `external_pull_requests`
- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests))
**Keyword type**: Job keyword. You can use it only as part of a job.
**Possible inputs**: An array including any number of:
- Paths to files.
- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory
and all its subdirectories, for example `path/to/directory/**/*`.
**Example of `only:changes`**:
```yaml
docker build:
script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
only:
refs:
- branches
changes:
- Dockerfile
- docker/scripts/*
- dockerfiles/**/*
```
In this example, `docker build` only runs in branch pipelines, and only if at least one of
these files changed:
- `Dockerfile`.
- Any file in `docker/scripts`
- Any file in `dockerfiles/` or any of its subdirectories.
**Additional details**:
- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`,
`changes` can't determine if a given file is new or old and always returns `true`.
- If you use `only: changes` with other refs, jobs ignore the changes and always run.
- If you use `except: changes` with other refs, jobs ignore the changes and never run.
**Related topics**:
- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples).
- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds),
you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests).
- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines).
````
|
