---
title: "GitLab CI/CD 파이프라인 최적화 방법"
description: "이 글은 GitLab CI/CD 파이프라인 핵심인 .gitlab-ci.yml 파일을 효율적으로 관리하고 유지 보수하는 5가지 핵심 방법을 소개합니다. include 키워드를 사용한 파일 분할, !reference 키워드와 extends 키워드를 사용한 파이프라인 상속, workflow 키워드를 사용한 파이프라인 전역 제어, YAML Anchors와 Aliases를 사용한 설정 재사용, 동적 파이프라인 구성을 위한 변수 설정이 그 내용입니다."
url: https://insight.infograb.net/blog/2024/08/28/gitlab-cicd/
source: content/generated/blog/2024-08-28-gitlab-cicd.md
---

GitLab CI/CD 파이프라인의 핵심인 `.gitlab-ci.yml` 파일은 프로젝트의 빌드, 테스트, 배포 과정을 정의합니다.  이 파일을 효율적으로 관리하고 유지 보수하려면, GitLab의 다양한 문법과 YAML 기능을 적절히 활용해야 합니다. 이 글에서는 `.gitlab-ci.yml` 파일의 유지 보수성을 높이는 5가지 핵심 방법을 소개하겠습니다.

## `include` 사용한 파일 분할

`include` 키워드는 GitLab CI/CD에서 파이프라인 설정을 여러 파일로 분할해 관리하는 기능입니다. 이 키워드를 사용해 복잡한 파이프라인을 여러 파일로 나눠 정의하면 설정 파일의 가독성과 유지 보수성을 크게 향상할 수 있습니다.

### `include` 사용법

`include` 키워드는 `.gitlab-ci.yml` 파일에서 다른 YAML 파일을 파이프라인에 포함하는 데 사용됩니다. 이 키워드를 사용하면 로컬 파일, 원격 파일, 다른 프로젝트의 파일을 가져올 수 있습니다. 그 결과, 파이프라인 구성의 모듈화와 재사용성을 개선할 수 있습니다. 구체적인 사용법을 살펴보겠습니다.

**로컬 파일 포함**

이는 프로젝트 내의 다른 YAML 파일을 포함하는 가장 간단하고 직접적인 방법입니다. 프로젝트의 루트 디렉터리를 기준으로 포함할 파이프라인 파일의 상대 경로를 아래와 같이 지정합니다.

```yaml
# .gitlab-ci.yml

include:
  # Local 파일 포함
  - local: "workflow/workflow.gitlab-ci.yml"
  - local: "template/build/build.gitlab-ci.yml"
```

<br/>

**원격 파일 포함**

GitLab에서는 원격 YAML 파일도 포함할 수 있습니다. 이 방법은 공용 템플릿이나 외부 리소스를 사용할 때 유용합니다. 아래 예시를 참고하세요.

```yaml
# .gitlab-ci.yml

include:
  # Remote 파일 포함
  - remote: 'https://gitlab.com/chad_infograb/pipeline-template/-/raw/main/template/test/test.gitlab-ci.yml'
```

:::note 참고

원격 파일을 `remote`로 포함할 때 브라우저에서 파일을 보는 **Blob URL**이 아닌, 파일 원본 내용을 그대로 표시하는 **Raw URL**을 사용해야 합니다.

![파일을 위치한 경로로 이동한 후, 오른쪽 상단의 Open raw 버튼을 클릭하면 Raw URL을 얻을 수 있습니다.](/img/blog/2024-08-28-gitlab-cicd-inline-01.png)
*파일을 위치한 경로로 이동한 후, 오른쪽 상단의 Open raw 버튼을 클릭하면 Raw URL을 얻을 수 있습니다.*

:::

<br/>

**다른 프로젝트 파일 포함**

같은 GitLab 인스턴스 내에 있는 다른 프로젝트의 YAML 파일도 포함할 수 있습니다. 아래 예시를 참고하세요.

```yaml
# .gitlab-ci.yml

include:
  # Project 파일 포함 (다른 GitLab 프로젝트의 파일)
  - project: "infograb/personal/chad/poc/pipeline-template"
    file: 
      - "/template/deploy/deploy.gitlab-ci.yml"
    ref: main
```

위 예시에서는 `infograb/personal/chad/poc/pipeline-template` 프로젝트의 `main` 브랜치에 있는 `deploy.gitlab-ci.yml` 파일을 현재 프로젝트의 CI/CD 파이프라인에 포함합니다.

<br/>

### `include`와 `inputs` 사용법

`include` 키워드와 함께 `inputs` 키워드를 사용하면 포함된 파일에 매개변수를 전달해 더 유연하게 설정할 수 있습니다. 아래 예시를 참고하세요.

```yaml
# .gitlab-ci.yml

include:
  # Local 파일 포함
  - local: 'workflow/workflow.gitlab-ci.yml'
    inputs:
      default_branch: main
```

위 예시에서는 `workflow/workflow.gitlab-ci.yml` 파일을 포함하면서 `default_branch` 변숫값을 `main`으로 설정합니다.

:::note 참고

`inputs` 키워드를 사용하려면 `include` 대상 파일에 아래와 같이 `spec` 섹션을 추가해야 합니다.

```yaml
# workflow/workflow.gitlab-ci.yml

# Input spec 정의
spec:
  inputs:
    default_branch:
      description: "The default branch name to use for workflow rules"
      type: string
      default: main
---

# Workflow 설정

...(중략)...
```

:::

<br/>

## `!reference`와 `extends` 사용한 파이프라인 상속

`!reference` 키워드와 `extends` 키워드는 GitLab CI/CD에서 설정 재사용성을 높이는 강력한 도구입니다. 두 키워드를 활용하면 파이프라인 구성을 모듈화하고 중복을 최소화해 복잡한 파이프라인도 쉽게 관리하고 확장할 수 있습니다.

### `!reference` 사용법

`!reference` 키워드는 이미 정의된 다른 항목 내용의 일부(예:`before_script`)를 참조하고 가져오는 데 사용됩니다. 아래 예시를 참고하세요.

```yaml
# template/build/build.gitlab-ci.yml

# 기본 before_script 정의 1
.before_script_1:
  before_script:
    - echo "Running before_script_1 tasks..."

# 기본 before_script 정의 2
.before_script_2:
  before_script:
    - !reference [.before_script_1, before_script]
    - echo "Running before_script_2 tasks..."
```

위 예시에서 `.before_script_2`는 `.before_script_1`의 내용 중 `before_script` 구성을 현재 섹션에 재사용하면서 추가 동작(`"Running before_script_2 tasks..."`)을 실행합니다.

<br/>

### `extends` 사용법

GitLab CI/CD YAML 파일에서 `extends` 키워드를 사용하면 기존의 작업(job)이나 설정을 기반으로 새로운 작업을 만들면서 일부를 수정하거나 추가할 수 있습니다. 다음 순서대로 사용하세요.

**기본 설정 정의**

먼저 공통된 설정을 위해 점(`.`)으로 시작하는 숨은 작업 템플릿을 정의합니다. 이 템플릿은 다른 작업에서 참조할 수 있습니다. 아래 예시를 참고하세요.

```yaml
# template/build/build.gitlab-ci.yml

# 기본 before_script 정의 1
.before_script_1:
  before_script:
    - echo "Running before_script_1 tasks..."

# 기본 before_script 정의 2
.before_script_2:
  before_script:
    - !reference [.before_script_1, before_script]
    - echo "Running before_script_2 tasks..."
```

:::note 참고

‘숨은 작업(Hidden Job)’이란?
GitLab CI/CD의 숨은 작업은 다른 작업에서 참조하는 템플릿 역할을 합니다. 이 작업은 파이프라인에서 직접 실행되지 않으며, 대신 다른 작업에서 재사용됩니다. 점(.)으로 시작하는 이름으로 정의되며, 예를 들어 `.before_script_1`, `.before_script_2`는 파이프라인에서 직접 실행되지 않고, 다른 작업에서 설정을 재사용하거나 확장할 때 활용됩니다.

:::

<br/>

**템플릿 상속**

이제 다른 작업에서 `extends` 키워드를 사용해 이 템플릿을 상속받아 사용할 수 있습니다. 아래 예시를 참고하세요.

```yaml
# template/build/build.gitlab-ci.yml

# Build Job 정의
build_job:
  stage: build
  extends: .before_script_2
  script:
    - echo "Starting the build process..."
    - echo "Compiling the code..."
    - echo "Running unit tests..."
    - echo "Packaging the application..."
    - echo "Build process completed successfully."
    - echo "This is the build artifact file" > ./output.txt
  artifacts:
    paths:
      - ./output.txt
```

위 예시에서 파이프라인은 `.before_script_2`에서 정의된 `before_script`를 확장해 빌드 작업을 수행합니다.

<br/>

## `workflow` 사용한 파이프라인 전역 제어

`workflow` 키워드를 사용하면 GitLab CI/CD 파이프라인의 실행 조건을 전역적으로 설정할 수 있습니다. 이 기능을 활용해 특정 상황에서만 파이프라인을 실행하도록 제어할 수 있습니다. 그 결과, 리소스를 효율적으로 사용하고 불필요한 빌드를 방지할 수 있습니다.

### `workflow` 사용법

```yaml
# workflow/workflow.gitlab-ci.yml

workflow:
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'
    - if: '$CI_COMMIT_REF_NAME =~ "$[[ inputs.default_branch ]]"'
    - when: never  # 위 조건에 해당하지 않는 브랜치에서는 파이프라인 실행 안 함
```

`workflow` 키워드는 위 예시와 같이 다음 조건을 설정합니다:

- 브랜치 이름이 `develop`일 때 파이프라인을 실행합니다.
- `release/*` 패턴과 일치하는 모든 브랜치(예:`release/v0.1.0`)에서 파이프라인을 실행합니다.
- `inputs.default_branch`로 정의된 값과 브랜치 이름이 일치할 때 파이프라인을 실행합니다. 이 변수는 파이프라인 설정 외부에서 전달됩니다.
- 위의 `if` 조건에 해당하지 않으면, 파이프라인을 실행하지 않습니다.

이러한 워크플로 설정은 `develop` 브랜치, `release/*` 패턴의 브랜치, 외부에서 전달된 기본 브랜치(`inputs.default_branch`로 정의)에서만 파이프라인을 실행합니다. 다른 모든 브랜치에서는 파이프라인이 실행되지 않습니다. 이 방식을 사용하면 작업마다 개별적으로 규칙(rules)을 정의할 필요가 없습니다.

<br/>

## YAML Anchors와 Aliases 사용한 설정 재사용

YAML은 Anchor(`&`)와 Alias(`*`) 기능을 기본으로 제공합니다. 이를 활용해 동일한 설정을 여러 곳에서 재사용할 수 있습니다. 이 기능은 GitLab CI/CD의 `.gitlab-ci.yml` 파일에도 동일하게 적용돼 중복된 설정을 줄이고 더 쉽게 유지 보수하도록 지원합니다. 다음 순서대로 사용하세요.

:::note 참고

Anchors와 Aliases는 YAML 문법 일부로, 동일한 파일 내에서만 사용할 수 있습니다. 따라서 `include` 키워드로 외부 파일을 가져올 때는 사용할 수 없습니다.

:::

### **Anchor 정의**

먼저 Anchor로 재사용할 설정을 정의합니다. Anchor는 `&` 기호를 사용해 정의합니다. 아래 예시를 참고하세요.

```yaml
# template/deploy/deploy.gitlab-ci.yml

.deploy_template: &deploy_template
  stage: deploy
  script:
    - echo "Starting the deployment process to $CI_COMMIT_REF_NAME..."
    - echo "Deploying application for $CI_COMMIT_REF_NAME..."
    - echo "Deployment completed successfully."
```

위 예시에서는 `&deploy_template`이라는 이름으로 배포 작업의 공통 설정을 정의합니다. 이 Anchor는 배포 단계(`stage: deploy`)와 배포 스크립트(`script`)를 포함하며, 배포 작업에서 수행될 일련의 명령어를 정의합니다.

<br/>

### Alias로 재사용

이제 다른 작업에서 `*` 기호를 사용해 위에서 정의한 Anchor를 참조할 수 있습니다. 아래 예시를 참고하세요.

```yaml
# template/deploy/deploy.gitlab-ci.yml

deploy_dev:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'

deploy_stg:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'

deploy_prd:
  <<: *deploy_template
  rules:
    - if: '$CI_COMMIT_REF_NAME == "main"'
```

위 예시에서 각 배포 작업(`deploy_dev`, `deploy_stg`, `deploy_prd`)은 `*deploy_template` Alias를 사용해 앞서 정의한 `&deploy_template` Anchor를 참조합니다. 이로써 모든 배포 작업이 동일한 배포 스크립트를 효율적으로 재사용할 수 있습니다.

:::note 참고

`<<` (Merge Key Language-Independent Type)
YAML은 위 표현을 사용해 하나 이상 지정된 map의 모든 키를 현재 map에 병합할 수 있습니다. 이미 존재하는 키에서 Alias는 병합되지 않습니다.

:::

<br/>

## 동적 파이프라인 구성

GitLab CI/CD에서는 다양한 조건에 따라 파이프라인 변수를 동적으로 설정할 수 있습니다. 이로써 파이프라인 유연성이 높아지며, 특정 상황에 맞게 동작을 조정할 수 있습니다. GitLab의 `variables` 키워드와 `rules` 키워드를 함께 사용하면, 파이프라인 실행 중 특정 조건에 따라 변숫값을 동적으로 변경할 수 있습니다.

### 조건에 맞게 동적으로 변수 설정

파이프라인 내에서 변수를 동적으로 설정하기 위해 `rules` 키워드를 사용합니다. `rules` 키워드로 특정 조건이 충족될 때 변숫값을 변경해 파이프라인 유연성을 높일 수 있습니다. 설정 방법은 아래와 같습니다.

**브랜치에 따라 빌드 명령어 변경**

다음 예시는 커밋이 발생한 브랜치에 따라 `BUILD_ENV` 변수를 동적으로 설정하는 방법을 보여줍니다.

```yaml
# template/build/build.gitlab-ci.yml

# Build Job 정의
build_job:
  stage: build
  extends: .before_script_2
  script:
    - echo "Starting the build process..."
    - echo "Compiling the code..."
    - echo "Running unit tests..."
    - echo "Packaging the application..."

    # 브랜치에 따라 다른 결과물 생성
    - echo "This is the build artifact for $BUILD_ENV environment" > ./output_$BUILD_ENV.txt
  artifacts:
    paths:
      - ./output_*.txt
  rules:
    - if: '$CI_COMMIT_REF_NAME == "develop"'
      variables:
        BUILD_ENV: "develop"
    - if: '$CI_COMMIT_REF_NAME =~ /^release\/.*$/'
      variables:
        BUILD_ENV: "release"
    - if: '$CI_COMMIT_REF_NAME == "main" || $CI_COMMIT_REF_NAME == "master"'
      variables:
        BUILD_ENV: "production"
```

위 예시에서 파이프라인은 `rules` 섹션에서 `BUILD_ENV` 변수를 정의해 브랜치에 따라 빌드 환경을 다르게 설정합니다.

각 브랜치에 `BUILD_ENV` 변수가 아래와 같이 설정됩니다.

- `develop` 브랜치: `BUILD_ENV`는 `"develop"`
- `release/*` 패턴의 브랜치: `BUILD_ENV`는 `"release"`
- `main` 또는 `master` 브랜치: `BUILD_ENV`는 `"production"`

브랜치별로 다음과 같이 빌드 결과물을 생성합니다.

- 파이프라인 실행 시, `script` 섹션에서 `BUILD_ENV` 값에 따라 다른 빌드 결과물을 생성합니다.
- 예시:
    - `develop` 브랜치: `output_develop.txt` 생성
    - `release/*` 브랜치: `output_release.txt` 생성
    - `main` 또는 `master` 브랜치: `output_production.txt` 생성
- 이러한 파일은 각 환경에 맞춘 빌드 결과물로, `artifacts` 섹션에 지정된 경로에 저장됩니다.

<br/>

## 맺음말

위에서 소개한 방법을 활용하면 GitLab CI/CD 파이프라인을 더 효율적이고 쉽게 유지 보수하도록 구성할 수 있습니다. 본문에서 언급한 코드 예시는 [다음 링크](https://gitlab.com/infograb-public/examples/pipeline-template)를 클릭하면 자세히 확인하실 수 있습니다. 감사합니다.

![build, test, deploy 파이프라인이 실행된 모습](/img/blog/2024-08-28-gitlab-cicd-inline-02.png)
*build, test, deploy 파이프라인이 실행된 모습*

::cta::

## 참고 자료

1. [Optimize GitLab CI/CD configuration files](https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html)
2. [Use CI/CD configuration from other files](https://docs.gitlab.com/ee/ci/yaml/includes.html)
3. [GitLab CI/CD ](https://docs.gitlab.com/ee/ci/yaml/workflow.html)[`workflow`](https://docs.gitlab.com/ee/ci/yaml/workflow.html)[ keyword](https://docs.gitlab.com/ee/ci/yaml/workflow.html)

::faq::

- q: GitLab CI/CD의 .gitlab-ci.yml 파일을 효율적으로 관리하는 방법은 무엇인가요?

    a: include 키워드로 파일 분할, !reference와 extends 키워드로 파이프라인 상속, workflow 키워드로 파이프라인 전역 제어, YAML Anchors와 Aliases로 설정 재사용, variables와 rules로 동적 파이프라인 구성의 다섯 가지가 핵심입니다. 이 방법들은 복잡한 파이프라인을 모듈화하고 중복을 줄여 가독성과 유지 보수성을 높입니다. .gitlab-ci.yml은 프로젝트의 빌드, 테스트, 배포 과정을 정의하는 GitLab CI/CD 파이프라인의 핵심 파일입니다.

- q: GitLab CI/CD의 include 키워드는 어떻게 쓰나요?

    a: include 키워드는 다른 YAML 파일을 파이프라인에 포함해 설정을 여러 파일로 나눠 관리하게 해 줍니다. local로 프로젝트 루트 기준 상대 경로의 파일을, remote로 원격 파일을, project와 file, ref로 같은 GitLab 인스턴스의 다른 프로젝트 파일을 가져올 수 있으며, remote에는 Blob URL이 아니라 Raw URL을 써야 합니다. inputs 키워드를 함께 쓰면 포함한 파일에 매개변수를 넘길 수 있는데, 이때 대상 파일에는 spec 섹션으로 inputs를 정의해야 합니다.

- q: GitLab CI/CD에서 !reference와 extends는 어떻게 다른가요?

    a: !reference는 이미 정의된 다른 항목의 일부, 예를 들어 before_script만 가져와 현재 섹션에서 재사용할 때 씁니다. extends는 기존 작업이나 템플릿 전체를 상속받아 새 작업을 만들면서 일부를 수정하거나 추가할 때 씁니다. 공통 설정은 보통 점(.)으로 시작하는 숨은 작업(Hidden Job)으로 정의하는데, 숨은 작업은 파이프라인에서 직접 실행되지 않고 다른 작업이 참조하는 템플릿 역할만 합니다.

- q: GitLab CI/CD의 workflow 키워드는 무엇에 쓰나요?

    a: workflow 키워드는 파이프라인 실행 조건을 전역으로 정해, 특정 상황에서만 파이프라인이 실행되도록 제어합니다. 예를 들어 workflow의 rules에 develop 브랜치, release/ 패턴의 브랜치, inputs로 전달된 기본 브랜치일 때만 실행하고 나머지는 when: never로 막을 수 있습니다. 이렇게 하면 작업마다 규칙을 따로 정의하지 않아도 되고, 불필요한 빌드를 막아 리소스를 효율적으로 쓸 수 있습니다.

- q: GitLab CI/CD에서 YAML Anchors와 동적 변수는 어떻게 활용하나요?

    a: YAML의 Anchor(&)로 공통 설정을 정의하고 Alias(*)와 병합 키로 여러 작업에서 재사용할 수 있지만, YAML 문법이라 같은 파일 안에서만 쓸 수 있고 include로 가져온 파일과는 함께 쓸 수 없습니다. variables와 rules 키워드를 함께 쓰면 실행 조건에 따라 변숫값을 동적으로 바꿀 수 있습니다. 예를 들어 BUILD_ENV를 develop 브랜치에서는 develop, release 브랜치에서는 release, main·master 브랜치에서는 production으로 설정해 환경별로 다른 빌드 결과물을 만들 수 있습니다.

::faq-end::

::button::[유지보수하기 쉬운 GitLab CI/CD 파이프라인을 설계하고 싶으신가요? GitLab 공식 파트너 인포그랩과 상담하세요!](https://insight.infograb.net/contact/)::
