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.
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:
### `artifacts` #### `artifacts:name` #### `artifacts:paths` #### `artifacts:reports` ##### `artifacts:reports:dast` ##### `artifacts:reports:sast`
Each keyword entry in the reference should use the following style:
### `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:
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.
In this example...: If the example needs extra details, add the clarification text below the example.
**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.
**Related topics**:If there are any other keywords or pages that relate to this keyword, add these links as list items here.
documentation for an example of the YAML reference style. The following example is a
shortened version of that documentation’s 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).