파이프라인 설정 키워드 문서화

요약

CI/CD YAML 구문 참조는 사용 및 업데이트를 보다 쉽게 하기 위해 표준 스타일을 사용합니다. 참조 정보는 가능한 한 단순하게 유지해야 하며, 확장된 세부 내용과 예시는 다른 페이지에 문서화해야 합니다. 모든 YAML 키워드는 참조에서 자체 섹션을 가져야 합니다.

CI/CD YAML 구문 참조는 사용 및 업데이트를 보다 쉽게 하기 위해 표준 스타일을 사용합니다.

참조 정보는 가능한 한 단순하게 유지해야 하며, 확장된 세부 내용과 예시는 다른 페이지에 문서화해야 합니다.

YAML 참조 구조#

모든 YAML 키워드는 참조에서 자체 섹션을 가져야 합니다. 섹션은 키워드가 논리적인 트리 구조를 따르도록 중첩되어야 합니다. 예를 들어:

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

YAML 참조 스타일#

참조의 각 키워드 항목은:

간단한 소개 섹션이 있어야 합니다. 소개에서는 키워드를 사용하는 데 필요한 기본 정보를 제공해야 합니다. 고급 세부 내용과 작업은 참조 페이지가 아닌 기능 페이지에 있어야 합니다.
키워드 이름을 제목으로 사용해야 합니다. 예를 들어:

### `artifacts`

다음 섹션을 포함해야 합니다:

키워드 유형

지원되는 값
keyword-name 예시
(선택 사항) 필요한 경우 다음 섹션도 포함할 수 있습니다:

추가 세부 내용

관련 항목
키워드 항목을 구분하기 위해 수평선(---)을 사용해야 합니다.

키워드 이름은 항상 백틱으로 감싸되 마지막에 :를 붙이지 않아야 합니다. 예: artifacts: 가 아닌 artifacts. 다른 키워드의 하위 키인 경우, 처음 사용할 때 artifacts:reports:dast와 같이 "상위" 키까지의 모든 하위 키를 작성합니다. 이후에는 dast와 같이 하위 키만 사용할 수 있습니다.

키워드 유형#

키워드는 job 키워드 또는 글로벌 키워드일 수 있습니다. default 섹션에서 사용할 수 있는 경우에는 그 점도 명시합니다. 예를 들어:

**키워드 유형**: 글로벌 키워드.
**키워드 유형**: Job 키워드. job의 일부로만 사용할 수 있습니다.
**키워드 유형**: Job 키워드. job의 일부로만 또는 [default: 섹션](#default)에서만 사용할 수 있습니다.

지원되는 값#

모든 지원되는 값과 기본값 또는 다른 GitLab 버전으로 인한 변경 사항 등 값에 대한 추가 세부 내용을 나열합니다. 예를 들어:

**지원되는 값**:

- `true` (정의하지 않은 경우 기본값) 또는 `false`.

**지원되는 값**:

- 단일 종료 코드.
- 종료 코드 배열.

**지원되는 값**:

- 긴 설명이 포함된 문자열.
- 설명이 포함된 파일의 경로.
  - 파일 위치는 프로젝트 디렉터리(`$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 job은 include: 키워드로 추가된 dast 설정을 확장하여 특정 사이트 프로파일과 스캐너 프로파일을 선택합니다.


예시에서 `new_keyword: "Description of $CI_COMMIT_BRANCH"`와 같이 CI/CD 변수를 사용하는 경우, **지원되는 값** 섹션에 CI/CD 변수가 지원된다는 설명이 있어야 합니다. 지원되는 값에 이 항목이 없는 경우 작성자에게 변수가 지원되는지 확인한 다음:

- 변수가 지원되는 경우 [**지원되는 값** 섹션에 CI/CD 변수를 추가](/19.1/development/cicd/cicd_reference_documentation_guide/#cicd-variables-with-keywords)합니다.

- 변수가 지원되지 않는 경우 예시에서 CI/CD 변수를 제거합니다.

### 추가 세부 내용

추가 세부 내용은 유용하지만 소개에 넣을 만큼 중요하지 않은 추가 정보의 비순서 목록이어야 합니다. 이 정보에는 다른 GitLab 버전에서 도입된 변경 사항이 포함될 수 있습니다. 예를 들어:

추가 세부 내용:

만료 시간은 아티팩트가 GitLab에 업로드되고 저장될 때 시작됩니다. 만료 시간이 정의되지 않은 경우 인스턴스 전체 설정으로 기본 설정됩니다.
만료 날짜를 재정의하고 아티팩트가 자동으로 삭제되지 않도록 보호하려면:
- job 페이지에서 유지를 선택합니다.
- GitLab 13.3 이상에서는 expire_in 값을 never로 설정합니다.


### 관련 항목

관련 항목은 관련 페이지에 대한 교차 링크의 비순서 목록이어야 하며 다음을 포함합니다:

- 키워드로 수행할 수 있는 특정 작업.

- 키워드의 고급 예시.

- 이 키워드와 함께 사용할 수 있는 다른 관련 키워드.

예를 들어:

관련 항목:

지정된 cache:key를 찾을 수 없는 경우 사용할 대체 캐시 키를 지정할 수 있습니다.
단일 job에서 여러 캐시 키를 사용할 수 있습니다.
더 많은 cache:key 예시는 일반적인 cache 사용 사례를 참조하세요.