.gitlab-ci.yml キーワードの文書化
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 セクションで使用できるのであれば、例えば、そのようなキーワードは使用しないでください：
**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).
可能な入力
可能な入力をすべて列挙し、デフォルトやGitLabのバージョン違いによる変更など、入力に関する特別な詳細も列挙します：
**Possible inputs**:
- `true` (default if not defined) or `false`.
**Possible inputs**:
- A single exit code.
- An array of exit codes.
**Possible inputs**:
- 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.
例keyword-name
キーワードの例。例を有効にするために必要な最小数の他のキーワードを使用します。例について説明が必要な場合は、例の後に追加してください：
**Example of `dast`**:
```yaml
stages:
- build
- dast
include:
- template: DAST.gitlab-ci.yml
dast:
dast_configuration:
site_profile: "Example Co"
scanner_profile: "Quick Passive Test"
```
In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword
to select a specific site profile and scanner profile.
その他の詳細
追加情報は、序文に書くほど重要ではないが、知っておくと便利な追加情報を、順序をつけずにリストしたものです。この情報には、異なるGitLabバージョンで導入された変更を含めることができます。例えば
**Additional details**:
- 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](../../administration/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`.
関連するトピック
関連トピックは、以下のような関連ページへのクロスリンクの順序なしリストでなければなりません：
- キーワードで達成できる具体的な作業。
- キーワードの高度な例
- このキーワードと一緒に使えるその他の関連キーワードです。
使用例：
**Related topics**:
- 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.