debian-mirror-gitlab/doc/development/cicd/cicd_reference_documentation_guide.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

154 lines
5 KiB
Markdown
Raw Normal View History

2021-06-08 01:23:25 +05:30
---
stage: Verify
2021-11-11 11:23:49 +05:30
group: Pipeline Authoring
2021-06-08 01:23:25 +05:30
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
---
2021-09-30 23:02:18 +05:30
# CI/CD YAML reference style guide **(FREE)**
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
The [CI/CD YAML reference](../../ci/yaml/index.md) uses a standard style to make it easier to use and update.
2021-06-08 01:23:25 +05:30
The reference information should be kept as simple as possible, and expanded details
2022-01-26 12:08:38 +05:30
and examples should be documented on other pages.
2021-06-08 01:23:25 +05:30
## 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:
2022-01-26 12:08:38 +05:30
```markdown
2021-06-08 01:23:25 +05:30
### `artifacts`
#### `artifacts:name`
#### `artifacts:paths`
#### `artifacts:reports`
##### `artifacts:reports:dast`
##### `artifacts:reports:sast`
```
## YAML reference style
2022-01-26 12:08:38 +05:30
Each keyword entry in the reference:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- Must have a simple introductory section. The introduction should give the fundamental
information needed to use the keyword. Advanced details and tasks should be in
feature pages, not the reference page.
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- Must use the keyword name as the title, for example:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
### `artifacts`
```
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- Should include the following sections:
- [Keyword type](#keyword-type)
- [Possible inputs](#possible-inputs)
- [Example of `keyword-name`](#example-of-keyword-name)
- (Optional) Can also include the following sections when needed:
- [Additional details](#additional-details)
- [Related topics](#related-topics)
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
The keyword name must always be in backticks without a final `:`, like `artifacts`, not `artifacts:`.
If it is a subkey of another keyword, write out all the subkeys to the "parent" key the first time it
is used, like `artifacts:reports:dast`. Afterwards, you can use just the subkey alone, like `dast`.
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
## Keyword type
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
The keyword can be either a job or global keyword. If it can be used in a `default`
section, make not of that as well, for example:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- `**Keyword type**: Global keyword.`
- `**Keyword type**: Job keyword. You can use it only as part of a job.`
- ``**Keyword type**: Job keyword. You can use it only as part of a job or in the [`default:` section](#default).``
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
### Possible inputs
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
List all the possible inputs, and any extra details about the inputs, such as defaults
or changes due to different GitLab versions, for example:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
**Possible inputs**:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- `true` (default if not defined) or `false`.
```
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
**Possible inputs**:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- A single exit code.
- An array of exit codes.
```
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
**Possible inputs**:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- A string with the long description.
- The path to a file that contains the description. Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67).
- The file location must be relative to the project directory (`$CI_PROJECT_DIR`).
- If the file is a symbolic link, it must be in the `$CI_PROJECT_DIR`.
- The `./path/to/file` and filename can't contain spaces.
```
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
### Example of `keyword-name`
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
An example of the keyword. Use the minimum number of other keywords necessary
to make the example valid. If the example needs explanation, add it after the example,
for example:
2021-06-08 01:23:25 +05:30
````markdown
2022-01-26 12:08:38 +05:30
**Example of `dast`**:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```yaml
stages:
- build
- dast
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
include:
- template: DAST.gitlab-ci.yml
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
dast:
dast_configuration:
site_profile: "Example Co"
scanner_profile: "Quick Passive Test"
```
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
to select a specific site profile and scanner profile.
````
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
### Additional details
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
The additional details should be an unordered list of extra information that is
useful to know, but not important enough to put in the introduction. This information
can include changes introduced in different GitLab versions. For example:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
**Additional details**:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- The expiration time period begins when the artifact is uploaded and stored on GitLab.
If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration).
- To override the expiration date and protect artifacts from being automatically deleted:
- Select **Keep** on the job page.
- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of
`expire_in` to `never`.
2021-06-08 01:23:25 +05:30
```
2022-01-26 12:08:38 +05:30
### Related topics
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
The related topics should be an unordered list of crosslinks to related pages, including:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
- Specific tasks that you can accomplish with the keyword.
- Advanced examples of the keyword.
- Other related keywords that can be used together with this keyword.
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
For example:
2021-06-08 01:23:25 +05:30
2022-01-26 12:08:38 +05:30
```markdown
2021-06-08 01:23:25 +05:30
**Related topics**:
2022-01-26 12:08:38 +05:30
- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key)
to use if the specified `cache:key` is not found.
- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job.
- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more
`cache:key` examples.
```