.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. 만약 다른 키워드의 하위 키이면, 첫 번째 사용 때 “parent” 키에 모든 하위 키를 작성해야 하고, 이후로는 dast와 같은 하위 키만 사용할 수 있습니다.

키워드 유형

키워드는 작업 또는 전역 키워드일 수 있습니다. default 섹션에서 사용할 수 있는 경우도 참고해야 합니다. 예를 들어:

  • **키워드 유형**: 전역 키워드.
  • **키워드 유형**: 작업 키워드. 작업의 일부로만 사용할 수 있습니다.
  • **키워드 유형**: 작업 키워드. 작업의 일부로만 사용할 수 있거나[`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` 및 파일 이름에는 공백이 포함되어서는 안됩니다.

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` 구성을 확장하여 특정 사이트 프로필 및 스캐너 프로필을 선택합니다.

추가 세부 정보

추가 세부 사항은 중요하지 않지만 알아 두면 유용한 추가 정보의 정렬되지 않은 목록이어야 합니다. 이 정보에는 다른 GitLab 버전에서 도입된 변경 사항이 포함될 수 있습니다. 예를 들어: 

**추가 세부 정보**:

- 아티팩트가 업로드되어 GitLab에 저장되면 유효 기간이 시작됩니다. 만약 유효 기간이 정의되지 않은 경우, [인스턴스 전체 설정](../../administration/settings/continuous_integration.md#default-artifacts-expiration)의 기본값으로 설정됩니다.
- 유효 기간을 무시하고 아티팩트를 자동으로 삭제되지 않도록 하려면:
  - 작업 페이지에서 **보존**을 선택합니다.
  - [GitLab 13.3 및 이후](https://gitlab.com/gitlab-org/gitlab/-/issues/22761)에서 `expire_in` 값을 `never`로 설정합니다.

관련 주제

관련 주제는 키워드와 함께 사용할 수 있는 관련 페이지로의 교차 링크의 정렬되지 않은 목록이어야 합니다. 예를 들어: 

**관련 주제**:

- 지정된 `cache:key`가 찾을 수 없는 경우 사용할 [대체 캐시 키](../caching/index.md#use-a-fallback-cache-key).
- 단일 작업에서 [여러 캐시 키](../caching/index.md#use-multiple-caches)를 사용할 수 있습니다.
- 더 많은 `cache:key` 예제를 보려면 [일반적인 `cache` 사용 사례](../caching/index.md#common-use-cases-for-caches)를 참조하세요.