Help us learn about your current experience with the documentation. Take the survey.

记录流水线配置关键词

CI/CD YAML 语法参考采用标准风格，使其更易于使用和更新。

参考信息应尽可能保持简单，扩展的详细信息和示例应记录在其他页面上。

YAML 参考结构

每个 YAML 关键词在参考中都必须有自己的部分。这些部分应该嵌套，以便关键词遵循逻辑树结构。例如：

### `artifacts`
#### `artifacts:name`
#### `artifacts:paths`
#### `artifacts:reports`
##### `artifacts:reports:dast`
##### `artifacts:reports:sast`

YAML 参考风格

参考中的每个关键词条目：

必须有简单的介绍部分。介绍应提供使用该关键词所需的基本信息。高级详细信息和任务应在功能页面中，而不是参考页面中。
必须使用关键词名称作为标题，例如：
```
### `artifacts`
```
应包括以下部分：
（可选）根据需要也可以包括以下部分：
- 附加信息
- 相关主题

关键词名称必须始终在反引号中，且末尾不带 :，例如 artifacts，而不是 artifacts:。如果它是另一个关键词的子键，第一次使用时需要写出所有子键到"父"键，例如 artifacts:reports:dast。之后，可以单独使用子键，例如 dast。

关键词类型

该关键词可以是作业关键词或全局关键词。如果可以在 default 部分中使用，也请注明。例如：

**关键词类型**: 全局关键词。
**关键词类型**: 作业关键词。您只能将其作为作业的一部分使用。
``关键词类型: 作业关键词。您只能将其作为作业的一部分或在 default: 部分中使用。```

支持的值

列出所有支持的值，以及关于这些值的任何额外信息，例如默认值或因不同 GitLab 版本而引起的变化。例如：

**支持的值**:

- `true`（如果未定义则为默认值）或 `false`。

**支持的值**:

- 单个退出代码。
- 退出代码数组。

**支持的值**:

- 包含长描述的字符串。
- 包含描述的文件路径。在 [GitLab 13.7](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67) 中引入。
  - 文件位置必须相对于项目目录（`$CI_PROJECT_DIR`）。
  - 如果文件是符号链接，它必须在 `$CI_PROJECT_DIR` 中。
  - `./path/to/file` 和文件名不能包含空格。

关键词与 CI/CD 变量

如果 CI/CD 变量可以与关键词一起使用，请在 支持的值 部分添加一行。例如：

**支持的值**:

- 包含长描述的字符串。
- [CI/CD 变量](../variables/where_variables_can_be_used.md#gitlab-ciyml-file)。

`keyword-name` 示例

该关键词的示例。使用最少数量的其他关键词使示例有效。如果示例需要解释，请在示例后添加，例如：

**`dast` 示例**:

```yaml
stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"
```

在此示例中，`dast` 作业扩展了通过 `include:` 关键词添加的 `dast` 配置，以选择特定的站点配置文件和扫描器配置文件。

如果示例使用 CI/CD 变量，例如 new_keyword: "Description of $CI_COMMIT_BRANCH"， 支持的值 部分必须说明支持 CI/CD 变量。如果支持值中缺少此项，请与作者确认是否支持变量，然后：

如果支持变量，将 CI/CD 变量添加到 支持的值 部分
如果不支持变量，请从示例中删除 CI/CD 变量。

附加信息

附加信息应该是有用但不足以放在介绍中的额外信息的无序列表。这些信息可以包括不同 GitLab 版本中引入的变化。例如：

**附加信息**:

- 过期时间周期从构件上传并存储在 GitLab 上时开始。
  如果未定义过期时间，则默认为[实例范围设置](../../administration/settings/continuous_integration.md#default-artifacts-expiration)。
- 要覆盖过期日期并防止构件被自动删除：
  - 在作业页面上选择 **Keep**。
  - [在 GitLab 13.3 及更高版本中](https://gitlab.com/gitlab-org/gitlab/-/issues/22761)，将 `expire_in` 的值设置为 `never`。