.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여야 합니다. 다른 키워드의 하위 키이 경우, 처음 사용될 때 “상위” 키에 모든 하위 키를 작성해야 합니다. 그 후에는 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)를 참조하세요.