GitLab 환경은 development, staging, production과 같이 애플리케이션의 특정 배포 타깃을 나타냅니다. 환경을 사용하면 서로 다른 구성을 관리하고 소프트웨어 수명 주기의 여러 단계에서 코드를 배포할 수 있습니다.

환경을 사용하면 다음을 할 수 있습니다.

• 배포 절차를 일관되고 반복 가능하게 유지합니다
• 어떤 코드가 어디에 배포되었는지 추적합니다
• 문제가 발생하면 이전 버전으로 롤백합니다
• 민감한 환경을 승인되지 않은 변경으로부터 보호합니다
• 환경별로 배포 변수를 제어해 보안 경계를 유지합니다
• 환경 상태를 모니터링하고 문제가 생기면 알림을 받습니다

환경 및 배포 보기#

사전 요구 사항:

• 비공개 프로젝트에서는 Reporter, Developer, Maintainer 또는 Owner 권한이 있어야 합니다. 환경 권한을 참고합니다.

다음 몇 가지 방법으로 특정 프로젝트의 환경 목록을 볼 수 있습니다.

• 사용 가능한(즉, 중지되지 않은) 환경이 하나 이상 있으면 프로젝트 개요 페이지에서 볼 수 있습니다.

  

• 왼쪽 사이드바에서 Operate > Environments를 선택합니다. 환경이 표시됩니다.

  

• 특정 환경의 배포 목록을 보려면 예를 들어 staging처럼 환경 이름을 선택합니다. 배포는 배포 job 이 생성한 뒤에만 이 목록에 표시됩니다.

  

• 배포 파이프라인의 모든 수동 job 목록을 보려면 Run ([play]) 드롭다운 목록을 선택합니다.

  

환경 URL#

환경 URL은 GitLab의 다음 몇 군데에 표시됩니다.

• 머지 리퀘스트에 링크로 표시됩니다.

  

• Environments 화면에 버튼으로 표시됩니다.

  

• Deployments 화면에 버튼으로 표시됩니다.

  

다음 조건을 만족하면 머지 리퀘스트에서 이 정보를 볼 수 있습니다.

• 머지 리퀘스트가 최종적으로 기본 브랜치(보통 main)에 머지됩니다.
• 해당 브랜치가 환경(예: staging 또는 production)에도 배포됩니다.

예시는 다음과 같습니다.

소스 파일에서 공개 페이지로 이동#

GitLab Route Maps를 사용하면 소스 파일에서 리뷰 앱용으로 설정된 환경의 공개 페이지로 바로 이동할 수 있습니다.

환경의 종류#

환경은 정적 환경이거나 동적 환경입니다.

정적 환경의 특징은 다음과 같습니다.

• 보통 이어지는 배포에서 재사용됩니다.
• 이름이 고정되어 있습니다. 예를 들어 staging 또는 production 입니다.
• 수동으로 또는 CI/CD 파이프라인의 일부로 생성됩니다.

동적 환경의 특징은 다음과 같습니다.

• 보통 CI/CD 파이프라인에서 생성되어 단일 배포에만 사용된 뒤 중지되거나 삭제됩니다.
• 이름이 동적이며, 대개 CI/CD 변수 값을 기반으로 합니다.
• 리뷰 앱의 기능입니다.

환경은 중지 job의 실행 여부에 따라 다음 세 가지 상태 중 하나를 가집니다.

• available: 환경이 존재합니다. 배포가 있을 수 있습니다.
• stopping: 중지 job 이 시작되었습니다. 중지 job 이 정의되어 있지 않으면 이 상태는 해당하지 않습니다.
• stopped: 중지 job 이 실행되었거나 사용자가 job을 수동으로 중지했습니다.

정적 환경 생성#

UI 또는 .gitlab-ci.yml 파일에서 정적 환경을 생성할 수 있습니다.

UI에서#

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

UI에서 정적 환경을 생성하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. Create an environment를 선택합니다.
4. 항목을 입력합니다.
5. Save를 선택합니다.

.gitlab-ci.yml 파일에서#

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

.gitlab-ci.yml 파일에서 정적 환경을 생성하려면 다음과 같이 합니다.

1. deploy Stage에 job을 정의합니다.
2. job에서 환경의 name과 url을 정의합니다. 파이프라인이 실행될 때 해당 이름의 환경이 없으면 새로 생성됩니다.

예를 들어 URL 이 https://staging.example.com 인 staging이라는 환경을 생성하려면 다음과 같이 합니다.

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com

동적 환경 생성#

동적 환경을 생성하려면 파이프라인마다 고유한 CI/CD 변수를 사용합니다.

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

.gitlab-ci.yml 파일에서 동적 환경을 생성하려면 다음과 같이 합니다.

1. deploy Stage에 job을 정의합니다.
2. job에서 다음 환경 속성을 정의합니다.
   • name: $CI_COMMIT_REF_SLUG 같은 관련 CI/CD 변수를 사용합니다. 환경 이름 앞에 고정 접두사를 선택적으로 붙일 수 있으며, 같은 접두사를 가진 환경은 UI에서 그룹으로 묶입니다.
   • url: 선택 사항입니다. 호스트명 앞에 $CI_ENVIRONMENT_SLUG 같은 관련 CI/CD 변수를 붙입니다.

다음 예시에서는 deploy_review_app job 이 실행될 때마다 고유한 값으로 환경 이름과 URL 이 정의됩니다.

deploy_review_app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: never
    - if: $CI_COMMIT_BRANCH

동적 환경 URL 설정#

일부 외부 호스팅 플랫폼은 배포마다 무작위 URL을 생성합니다. 예를 들면 https://94dd65b.amazonaws.com/qa-lambda-1234567 같은 형태입니다. 이 때문에 .gitlab-ci.yml 파일에서 해당 URL을 참조하기가 어렵습니다.

생성된 URL을 dotenv 변수로 받아 environment:url에 전달하도록 배포 job을 구성할 수 있습니다. job에 artifacts:reports:dotenv를 지정합니다. job 이 끝나면 GitLab 이 dotenv 리포트를 파싱해 변수 값으로 environment:url을 확장합니다. 이렇게 지정된 URL은 UI에서 확인할 수 있습니다.

https://$DYNAMIC_ENVIRONMENT_URL처럼 고정 접두사와 변수를 함께 쓸 수도 있습니다. DYNAMIC_ENVIRONMENT_URL 이 example.com 이면 결과는 https://example.com 입니다.

전체 흐름은 job 종료 후 동적 URL 설정을 참고합니다.

다음 예시에서 리뷰 앱은 머지 리퀘스트마다 새 환경을 생성합니다.

• review job은 푸시할 때마다 트리거되어 review/your-branch-name이라는 환경을 생성하거나 업데이트합니다. 환경 URL은 $DYNAMIC_ENVIRONMENT_URL로 설정됩니다.
• review job 이 끝나면 GitLab 이 review/your-branch-name 환경의 URL을 업데이트합니다. deploy.env 리포트를 파싱해 변수를 추출하고, 이를 사용해 environment:url을 확장해 설정합니다.

review:
  script:
    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
  artifacts:
    reports:
      dotenv: deploy.env                                                       # Report back dotenv file to rails.
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
    on_stop: stop_review

stop_review:
  script:
    - ./teardown-environment
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

다음 사항에 유의합니다.

• stop_review는 dotenv 리포트 아티팩트를 생성하지 않으므로 DYNAMIC_ENVIRONMENT_URL 환경 변수를 인식하지 못합니다. 따라서 stop_review job에는 environment:url을 설정하지 않아야 합니다.
• 환경 URL 이 유효하지 않으면(예: URL 형식이 잘못된 경우) 시스템은 환경 URL을 업데이트하지 않습니다.
• stop_review에서 실행되는 스크립트가 리포지터리에만 존재해 GIT_STRATEGY: none 이나 GIT_STRATEGY: empty를 쓸 수 없다면, 해당 job에 머지 리퀘스트 파이프라인을 구성합니다. 이렇게 하면 기능 브랜치가 삭제된 뒤에도 러너가 리포지터리를 가져올 수 있습니다. 자세한 내용은 러너용 Ref Spec을 참고합니다.

Add-Content -Path deploy.env -Value "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL"

환경의 배포 티어#

같은 그룹에 속한 프로젝트라도 동일한 배포 티어에 서로 다른 환경 이름을 쓸 수 있습니다. 예를 들어 같은 티어에 대해 어떤 프로젝트는 production을, 다른 프로젝트는 custom-portal을 쓸 수 있습니다. 그룹 보호된 환경은 이러한 차이를 배포 티어로 처리합니다.

사용할 수 있는 배포 티어는 다음과 같습니다.

• development
• testing
• staging
• production
• other

GitLab은 다음 패턴을 기준으로 환경 이름에서 배포 티어를 추정합니다.

어떤 패턴에도 일치하지 않는 환경 이름은 other로 추정됩니다.

자동 추정을 피하려면 deployment_tier 키워드를 사용합니다.

배포 티어는 UI에서 설정할 수 없습니다.

환경 이름 변경#

환경의 이름은 변경할 수 없습니다.

환경 이름 변경과 같은 결과를 얻으려면 다음과 같이 합니다.

1. 기존 환경을 중지합니다.
2. 기존 환경을 삭제합니다.
3. 원하는 이름으로 새 환경을 생성합니다.

CI/CD 변수#

환경과 배포를 원하는 대로 구성하기 위해 사전 정의된 CI/CD 변수를 사용하거나 사용자 정의 CI/CD 변수를 정의할 수 있습니다.

CI/CD 변수의 환경 범위 제한#

기본적으로 모든 CI/CD 변수는 파이프라인의 모든 job에서 사용할 수 있습니다. job의 테스트 도구가 침해되면 해당 도구가 job에서 사용할 수 있는 모든 CI/CD 변수를 가져오려 할 수 있습니다. 이러한 공급망 공격을 완화하려면 민감한 변수의 환경 범위를 그 변수가 필요한 job 으로만 제한해야 합니다.

변수를 사용할 수 있는 환경을 지정해 CI/CD 변수의 환경 범위를 제한합니다. 기본 환경 범위는 와일드카드 * 이므로 모든 job 이 변수에 접근할 수 있습니다.

특정 환경을 선택하려면 정확히 일치하는 값을 지정할 수 있습니다. 예를 들어 변수의 환경 범위를 production으로 설정하면 환경이 production 인 job만 변수에 접근할 수 있습니다.

review/*처럼 와일드카드 일치(*)를 사용해 리뷰 앱 전체와 같은 특정 환경 그룹을 선택할 수도 있습니다.

예를 들어 다음 네 개의 환경이 있다고 가정합니다.

• production
• staging
• review/feature-1
• review/feature-2

각 환경 범위는 다음과 같이 일치합니다.

환경 범위가 지정된 변수는 rules 또는 include와 함께 사용하지 않아야 합니다. 파이프라인 생성 시점에 GitLab 이 파이프라인 구성을 검증할 때 변수가 정의되어 있지 않을 수 있습니다.

환경 검색#

히스토리

• GitLab 17.4에서 일반 공급으로 전환되었습니다. 기능 플래그 enable_environments_search_within_folder가 제거되었습니다.

이름으로 환경을 검색하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. 검색 창에 검색어를 입력합니다.
   • 검색어는 세 글자 이상이어야 합니다.
   • 일치 판정은 환경 이름의 앞부분부터 적용됩니다.
     • 예를 들어 devel은 환경 이름 development와 일치하지만 elop은 일치하지 않습니다.
   • 폴더 이름 형식을 쓰는 환경에서는 기본 폴더 이름 뒤부터 일치 판정이 적용됩니다.
     • 예를 들어 이름이 review/test-app 이면 검색어 test가 review/test-app과 일치합니다.
     • review/test처럼 폴더 이름을 앞에 붙여 검색해도 review/test-app과 일치합니다.

비슷한 환경 그룹으로 묶기#

UI에서 환경을 접을 수 있는 섹션으로 묶을 수 있습니다.

예를 들어 모든 환경 이름이 review로 시작하면 UI에서 해당 제목 아래에 환경이 묶여 표시됩니다.

다음 예시는 환경 이름을 review로 시작하는 방법을 보여 줍니다. $CI_COMMIT_REF_SLUG 변수에는 실행 시점의 브랜치 이름이 채워집니다.

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG

환경 중지#

환경을 중지하면 해당 배포에 타깃 서버에서 접근할 수 없게 됩니다. 환경을 삭제하려면 먼저 중지해야 합니다.

on_stop 액션으로 환경을 중지할 때, 해당 job 이 보관 처리되지 않았다면 job 이 실행됩니다.

UI로 환경 중지#

GitLab UI에서 환경을 중지하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. 중지하려는 환경 옆에서 Stop을 선택합니다.
4. 확인 대화 상자에서 Stop environment를 선택합니다.

on_stop 액션을 실행하지 않고 환경을 중지할 수도 있습니다.

기본 중지 동작#

GitLab은 연결된 브랜치가 삭제되거나 머지되면 환경을 자동으로 중지합니다. 이 동작은 명시적인 on_stop CI/CD job 이 정의되어 있지 않아도 유지됩니다.

다만 이슈 428625는 production과 staging 환경은 명시적인 on_stop CI/CD job 이 정의된 경우에만 중지되도록 이 동작을 변경할 것을 제안하고 있습니다.

Environments API의 auto_stop_setting 파라미터로 환경의 중지 동작을 구성할 수 있습니다.

브랜치가 삭제될 때 환경 중지#

브랜치가 삭제될 때 환경이 중지되도록 구성할 수 있습니다.

다음 예시에서는 deploy_review job 이 stop_review job을 호출해 환경을 정리하고 중지합니다.

• 두 job은 rules 또는 only/except 구성이 같아야 합니다. 그렇지 않으면 deploy_review job 이 포함된 모든 파이프라인에 stop_review job 이 포함되지 않을 수 있고, 환경을 자동으로 중지하는 action: stop을 트리거할 수 없습니다.
• action: stop job은 환경을 시작한 job보다 뒤 Stage에 있으면 실행되지 않을 수 있습니다.
• 머지 리퀘스트 파이프라인을 사용할 수 없다면 stop_review job에서 GIT_STRATEGY를 none 또는 empty로 설정합니다. 그러면 브랜치가 삭제된 뒤에도 러너가 코드를 체크아웃하려 시도하지 않습니다.

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review

stop_review:
  stage: deploy
  script:
    - echo "Remove review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual

머지 리퀘스트가 머지되거나 닫힐 때 환경 중지#

머지 리퀘스트 파이프라인 구성을 사용하면 stop 트리거가 자동으로 활성화됩니다.

다음 예시에서는 deploy_review job 이 stop_review job을 호출해 환경을 정리하고 중지합니다.

• Pipelines must succeed 설정이 켜져 있으면, stop_review job에 allow_failure: true 키워드를 구성해 이 job 이 파이프라인과 머지 리퀘스트를 막지 않도록 할 수 있습니다.

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop_review
  rules:
    - if: $CI_MERGE_REQUEST_ID

stop_review:
  stage: deploy
  script:
    - echo "Remove review app"
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual

일정 기간이 지난 후 환경 중지#

환경이 일정 기간이 지난 후 자동으로 중지되도록 설정할 수 있습니다.

.gitlab-ci.yml 파일에 environment:auto_stop_in 키워드를 지정합니다. 기간은 1 hour and 30 minutes 또는 1 day처럼 자연어로 지정합니다. 해당 기간이 지나면 GitLab 이 환경을 중지하는 job을 자동으로 시작합니다.

다음 예시의 동작은 아래와 같습니다.

• 머지 리퀘스트의 커밋마다 review_app job 이 실행되어 최신 변경 사항을 환경에 배포하고 만료 기간을 초기화합니다.
• 환경이 일주일 넘게 비활성 상태이면 GitLab 이 stop_review_app job을 자동으로 실행하여 환경을 중지합니다.

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop_review_app
    auto_stop_in: 1 week
  rules:
    - if: $CI_MERGE_REQUEST_ID

stop_review_app:
  script: stop-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  rules:
    - if: $CI_MERGE_REQUEST_ID
      when: manual

environment:action 키워드를 사용하면 환경의 중지 예정 시각을 초기화할 수 있습니다. 자세한 내용은 준비 또는 검증 목적의 환경 접근을 참고합니다.

환경의 중지 예정 날짜 및 시각 확인#

환경이 일정 기간이 지난 후 중지되도록 예약되어 있으면 만료 날짜와 시각을 확인할 수 있습니다.

환경의 만료 날짜와 시각을 확인하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. 환경 이름을 선택합니다.

만료 날짜와 시각은 왼쪽 상단 모서리의 환경 이름 옆에 표시됩니다.

환경의 중지 예정 날짜 및 시각 재정의#

환경이 일정 기간이 지난 후 중지되도록 예약되어 있으면 만료 시점을 재정의할 수 있습니다.

UI에서 환경의 만료를 재정의하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. 환경 이름을 선택합니다.
4. 오른쪽 상단 모서리에서 압정 아이콘([thumbtack])을 선택합니다.

.gitlab-ci.yml에서 환경의 만료를 재정의하려면 다음 단계를 수행합니다.

1. 프로젝트의 .gitlab-ci.yml을 엽니다.
2. 해당 배포 job의 auto_stop_in 설정을 auto_stop_in: never로 변경합니다.

auto_stop_in 설정이 재정의되며, 환경은 수동으로 중지할 때까지 활성 상태를 유지합니다.

오래된 환경 정리#

프로젝트에서 예전 환경을 중지하려면 오래된 환경을 정리합니다.

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

오래된 환경을 정리하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. Clean up environments를 선택합니다.
4. 오래된 환경으로 판단할 기준 날짜를 선택합니다.
5. Clean up을 선택합니다.

지정한 날짜 이후로 업데이트되지 않은 활성 환경이 중지됩니다. 보호된 환경은 대상에서 제외되며 중지되지 않습니다.

환경이 중지될 때 파이프라인 job 실행#

히스토리

• 기능 플래그 environment_stop_actions_include_all_finished_deployments가 GitLab 16.9에서 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 기능 플래그 environment_stop_actions_include_all_finished_deployments가 GitLab 17.0에서 제거되었습니다.

환경의 배포 job에 on_stop 액션을 지정하여 해당 환경의 중지 job을 정의할 수 있습니다.

환경이 중지되면 가장 최근에 완료된 파이프라인에서 완료된 배포의 중지 job 이 실행됩니다. 배포 또는 파이프라인은 성공, 취소, 실패 상태이면 완료된 것으로 간주됩니다.

사전 요구 사항:

• 배포 job과 중지 job의 rules 또는 only/except 설정이 같아야 합니다.
• 중지 job에 다음 키워드가 정의되어 있어야 합니다.
  • when. 다음 중 한 위치에 정의합니다.
    • job 수준.
    • rules 절 안. rules와 when: manual을 함께 사용하는 경우 job 이 실행되지 않아도 파이프라인이 완료될 수 있도록 allow_failure: true도 설정합니다.
  • environment:name
  • environment:action

다음 예시의 동작은 아래와 같습니다.

• review_app job 이 완료된 후 stop_review_app job을 호출합니다.
• stop_review_app은 when에 정의된 값에 따라 트리거됩니다. 이 예시에서는 manual로 설정되어 있으므로 실행하려면 GitLab UI에서 수동 액션이 필요합니다.
• GIT_STRATEGY는 none으로 설정되어 있습니다. stop_review_app job 이 자동으로 트리거되는 경우, 러너는 브랜치가 삭제된 뒤에 코드를 체크아웃하려고 시도하지 않습니다.

review_app:
  stage: deploy
  script: make deploy-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review_app

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

환경의 다중 중지 액션#

한 환경에 여러 중지 액션을 병렬로 설정하려면 .gitlab-ci.yml 파일에 정의된 동일 environment의 여러 배포 job에 on_stop 키워드를 지정합니다.

환경이 중지되면 성공한 배포 job의 on_stop 액션만 정해진 순서 없이 병렬로 실행됩니다.

다음 예시에서 test 환경에는 두 개의 배포 job 이 있습니다.

• deploy-to-cloud-a
• deploy-to-cloud-b

환경이 중지되면 시스템은 on_stop 액션인 teardown-cloud-a와 teardown-cloud-b를 병렬로 실행합니다.

deploy-to-cloud-a:
  script: echo "Deploy to cloud a"
  environment:
    name: test
    on_stop: teardown-cloud-a

deploy-to-cloud-b:
  script: echo "Deploy to cloud b"
  environment:
    name: test
    on_stop: teardown-cloud-b

teardown-cloud-a:
  script: echo "Delete the resources in cloud a"
  environment:
    name: test
    action: stop
  when: manual

teardown-cloud-b:
  script: echo "Delete the resources in cloud b"
  environment:
    name: test
    action: stop
  when: manual

on_stop 액션을 실행하지 않고 환경 중지#

히스토리

• UI의 Force stop 옵션이 GitLab 19.5에서 도입되었습니다.

환경을 강제 중지하면 해당 환경의 on_stop 액션을 건너뛸 수 있습니다. 이 옵션은 다음과 같은 경우에 사용합니다.

• 중지 job을 실행하는 데 컴퓨트 할당량을 사용하지 않고 여러 환경을 삭제합니다.
• stopping 상태에 멈춘 환경을 복구합니다. 예를 들어 auto_stop_in 타이머가 중지 job을 트리거하기 전에 소스 브랜치가 삭제된 경우에 발생할 수 있습니다.

환경을 강제 중지하면 환경이 즉시 중지됨으로 표시되고 Stopped 탭으로 이동합니다. GitLab은 on_stop job을 실행하거나 기다리지 않으므로 해당 job의 정리 단계는 실행되지 않습니다. 이 정리는 직접 수행해야 합니다. GitLab은 delete_resources: on_stop을 사용하는 GitLab 관리 Kubernetes 리소스는 여전히 삭제합니다.

강제 중지는 이미 대기 중이거나 실행 중인 on_stop job을 취소하지 않습니다. job이 나중에 끝나더라도 환경은 중지된 상태로 유지됩니다. job이 실행되지 않게 하려면 직접 취소합니다.

사전 요구 사항:

• 보호되지 않은 환경을 강제 중지하려면 최소한 Developer 권한이 있어야 합니다.
• 보호된 환경을 강제 중지하려면 해당 환경에 배포할 수 있는 권한이 있어야 합니다.

GitLab UI에서 환경을 강제 중지하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. 환경이 사용 가능하고 on_stop 액션이 정의되어 있다면:
   1. 환경 옆에서 Stop을 선택합니다.
   2. 확인 대화 상자에서 Force stop 체크박스를 선택합니다.
   3. Force stop environment를 선택합니다.
4. 환경이 stopping 상태에 멈춰 있다면:
   1. 환경 옆에서 More actions(⋮) > Force stop environment를 선택합니다.
   2. 확인 대화 상자에서 Force stop environment를 선택합니다. 또는 환경 세부 정보 페이지에서 Force stop을 선택합니다.

환경 중지 API를 force=true 파라미터와 함께 사용해서도 환경을 강제 중지할 수 있습니다.

환경 삭제#

환경과 그 모든 배포를 제거하려면 환경을 삭제합니다.

사전 요구 사항:

• Developer, Maintainer, Owner 중 하나의 권한이 있어야 합니다.
• 환경을 삭제하려면 먼저 환경을 중지해야 합니다.

환경을 삭제하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Operate > Environments를 선택합니다.
3. Stopped 탭을 선택합니다.
4. 삭제할 환경 옆에서 Delete environment를 선택합니다.
5. 확인 대화 상자에서 Delete environment를 선택합니다.

준비 또는 검증 목적의 환경 접근#

히스토리

• GitLab 17.7에서 prepare 및 access 액션에 대해 auto_stop_in을 초기화하도록 업데이트되었습니다.

검증이나 준비 등 여러 목적으로 환경에 접근하는 job을 정의할 수 있습니다. 이 방식은 배포 생성을 사실상 건너뛰므로 CD 워크플로를 더 정확하게 조정할 수 있습니다.

이렇게 하려면 job의 environment 섹션에 action: prepare, action: verify, action: access 중 하나를 추가합니다.

build:
  stage: build
  script:
    - echo "Building the app"
  environment:
    name: staging
    action: prepare
    url: https://staging.example.com

이렇게 하면 환경 범위 변수에 접근할 수 있고, 인가되지 않은 접근으로부터 빌드를 보호할 수 있습니다. 또한 오래된 배포 job 방지 기능을 피하는 데에도 효과적입니다.

환경이 일정 기간이 지난 후 중지되도록 설정되어 있으면, access 또는 prepare 액션을 사용하는 job 이 예약된 중지 시각을 초기화합니다. 이때 해당 환경에 대한 가장 최근 성공 배포 job의 environment:auto_stop_in 값이 사용됩니다. 예를 들어 가장 최근 배포가 auto_stop_in: 1 week를 사용했고 이후 action: access job 이 해당 환경에 접근하면, 환경은 그 접근 job 이 완료된 시점부터 일주일 후에 중지되도록 다시 예약됩니다.

예약된 중지 시각을 변경하지 않고 환경에 접근하려면 verify 액션을 사용합니다.

환경 인시던트 관리#

프로덕션 환경은 통제할 수 없는 원인을 포함해 예기치 않게 다운될 수 있습니다. 예를 들어 외부 의존성, 인프라, 사람의 실수로 인해 환경에 심각한 문제가 발생할 수 있습니다. 다음과 같은 경우입니다.

• 의존하는 클라우드 서비스가 다운됩니다.
• 서드 파티 라이브러리가 업데이트되어 애플리케이션과 호환되지 않습니다.
• 서버의 취약한 엔드포인트에 누군가 DDoS 공격을 수행합니다.
• 운영자가 인프라를 잘못 설정합니다.
• 프로덕션 애플리케이션 코드에 버그가 유입됩니다.

즉시 대응이 필요한 심각한 문제가 발생했을 때 알림을 받으려면 인시던트 관리를 사용할 수 있습니다.

환경의 최신 알림 확인#

알림 통합을 설정하면 환경 페이지에 환경 알림이 표시됩니다. 심각도가 가장 높은 알림이 표시되므로 즉시 대응이 필요한 환경을 파악할 수 있습니다.

알림을 발생시킨 문제가 해결되면 해당 알림은 제거되며 환경 페이지에 더 이상 표시되지 않습니다.

알림에 롤백이 필요하면 환경 페이지에서 배포 탭을 선택하고 롤백할 배포를 선택할 수 있습니다.

자동 롤백#

일반적인 지속적 배포 워크플로에서는 CI 파이프라인이 프로덕션에 배포하기 전에 모든 커밋을 테스트합니다. 그러나 문제가 있는 코드가 프로덕션까지 도달할 수 있습니다. 예를 들어 논리적으로는 올바르지만 비효율적인 코드는 심각한 성능 저하를 일으키면서도 테스트를 통과할 수 있습니다. 운영자와 SRE는 이러한 문제를 최대한 빨리 발견하기 위해 시스템을 모니터링합니다. 문제가 있는 배포를 발견하면 이전의 안정적인 버전으로 롤백할 수 있습니다.

GitLab 자동 롤백은 심각 알림이 감지되면 롤백을 자동으로 트리거하여 이 워크플로를 단순화합니다. GitLab 이 롤백 대상 환경을 올바르게 선택하려면 알림에 환경 이름이 담긴 gitlab_environment_name 키가 포함되어야 합니다. GitLab은 가장 최근에 성공한 배포를 선택해 다시 배포합니다.

GitLab 자동 롤백의 제약 사항은 다음과 같습니다.

• 알림이 감지된 시점에 배포가 실행 중이면 롤백을 건너뜁니다.
• 롤백은 3분에 한 번만 수행할 수 있습니다. 여러 알림이 동시에 감지되어도 롤백은 한 번만 수행됩니다.

GitLab 자동 롤백은 기본적으로 꺼져 있습니다. 켜려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Automatic deployment rollbacks를 확장합니다.
4. Enable automatic rollbacks 체크박스를 선택합니다.
5. Save changes를 선택합니다.

환경 권한#

권한에 따라 공개 프로젝트와 비공개 프로젝트에서 환경을 다루는 방식이 달라집니다.

환경 보기#

• 공개 프로젝트에서는 멤버가 아닌 사용자를 포함해 누구나 환경 목록을 볼 수 있습니다.
• 비공개 프로젝트에서는 환경 목록을 보려면 Reporter, Developer, Maintainer, Owner 중 하나의 권한이 있어야 합니다.

환경 생성 및 업데이트#

• 새 환경을 만들거나 보호되지 않은 기존 환경을 업데이트하려면 Developer, Maintainer, Owner 중 하나의 권한이 있어야 합니다.
• 보호된 환경의 경우 Allowed to deploy 목록에 포함되어 있어야 합니다.

환경 중지 및 삭제#

• 보호되지 않은 환경을 중지하거나 삭제하려면 Developer, Maintainer, Owner 중 하나의 권한이 있어야 합니다.
• 환경이 보호되어 있고 접근 권한이 없으면 해당 환경을 중지하거나 삭제할 수 없습니다.

보호된 환경에서 배포 job 실행#

보호된 브랜치에 푸시하거나 머지할 수 있는 경우:

• Reporter, Developer, Maintainer, Owner 중 하나의 권한이 있어야 합니다.

보호된 브랜치에 푸시할 수 없는 경우:

• Reporter 권한을 가진 그룹의 구성원이어야 합니다.

보호된 환경에 대한 배포 전용 접근을 참고합니다.

웹 터미널(사용 중단)#

배포 서비스(예: Kubernetes 통합)를 사용해 환경에 배포하는 경우, GitLab 이 해당 환경에 대한 터미널 세션을 열 수 있습니다. 이를 통해 웹 브라우저를 벗어나지 않고 문제를 디버깅할 수 있습니다.

웹 터미널은 컨테이너 기반 배포이므로 에디터 같은 기본 도구가 없는 경우가 많고, 언제든 중지되거나 재시작될 수 있습니다. 이 경우 변경 사항이 모두 사라집니다. 웹 터미널은 종합적인 온라인 IDE가 아니라 디버깅 도구로 사용합니다.

웹 터미널의 특징은 다음과 같습니다.

• 프로젝트의 Maintainer와 Owner만 사용할 수 있습니다.
• 활성화되어 있어야 합니다.

UI에서 웹 터미널을 보려면 다음 중 한 가지 방법을 사용합니다.

• Actions 메뉴에서 Terminal을 선택합니다.

  

• 특정 환경 페이지의 오른쪽에서 Terminal([terminal])을 선택합니다.

버튼을 선택하면 터미널 세션이 연결됩니다. 다른 터미널과 동일하게 동작합니다. 배포로 생성된 컨테이너 안에 있으므로 다음 작업을 수행할 수 있습니다.

• 셸 명령을 실행하고 응답을 실시간으로 확인합니다.
• 로그를 확인합니다.
• 설정이나 코드 수정을 시험해 봅니다.

같은 환경에 여러 터미널을 열 수 있습니다. 각 터미널은 자체 셸 세션을 가지며 screen 이나 tmux 같은 멀티플렉서도 사용할 수 있습니다.

관련 주제#

• Kubernetes 대시보드
• 배포
• 보호된 환경
• 환경 대시보드
• 배포 안전성

문제 해결#

action: stop job 이 실행되지 않는 경우#

on_stop job을 설정했는데도 환경이 중지되지 않는 경우가 있습니다. 이는 action: stop 이 설정된 job 이 stages: 또는 needs: 설정 때문에 실행 가능한 상태가 아닐 때 발생합니다.

예를 들면 다음과 같습니다.

• 환경이 시작되는 Stage에 실패한 job 이 함께 있을 수 있습니다. 그러면 이후 Stage의 job은 시작되지 않습니다. 해당 환경의 action: stop job도 이후 Stage에 있으면 시작될 수 없어 환경이 삭제되지 않습니다.
• action: stop job 이 아직 완료되지 않은 job에 의존하고 있을 수 있습니다.

필요할 때 action: stop 이 항상 실행되도록 하려면 다음 방법을 사용할 수 있습니다.

• 두 job을 같은 Stage에 둡니다.

  stages:
    - build
    - test
    - deploy
  
  ...
  
  deploy_review:
    stage: deploy
    environment:
      name: review/$CI_COMMIT_REF_SLUG
      url: https://$CI_ENVIRONMENT_SLUG.example.com
      on_stop: stop_review
  
  stop_review:
    stage: deploy
    environment:
      name: review/$CI_COMMIT_REF_SLUG
      action: stop
    when: manual
  

• action: stop job에 needs 항목을 추가하여 job 이 Stage 순서와 무관하게 시작될 수 있게 합니다.

  stages:
    - build
    - test
    - deploy
    - cleanup
  
  ...
  
  deploy_review:
    stage: deploy
    environment:
      name: review/$CI_COMMIT_REF_SLUG
      url: https://$CI_ENVIRONMENT_SLUG.example.com
      on_stop: stop_review
  
  stop_review:
    stage: cleanup
    needs:
      - deploy_review
    environment:
      name: review/$CI_COMMIT_REF_SLUG
      action: stop
    when: manual
  

오류: job would create an environment with an invalid parameter#

프로젝트가 동적 환경을 생성하도록 구성되어 있으면, 동적으로 생성된 파라미터를 환경 생성에 사용할 수 없어 배포 job에서 다음 오류가 발생할 수 있습니다.

This job could not be executed because it would create an environment with an invalid parameter.

예를 들어 프로젝트의 .gitlab-ci.yml 이 다음과 같다고 가정합니다.

deploy:
  script: echo
  environment: production/$ENVIRONMENT

$ENVIRONMENT 변수가 파이프라인에 존재하지 않으므로 GitLab은 이름이 production/ 인 환경을 생성하려고 시도하며, 이 이름은 환경 이름 제약 조건에 맞지 않습니다.

이 문제는 다음 방법 중 하나로 해결합니다.

• 배포 job에서 environment 키워드를 제거합니다. GitLab은 유효하지 않은 이 키워드를 이미 무시하고 있으므로, 키워드를 제거해도 배포 파이프라인은 그대로 유지됩니다.
• 변수가 파이프라인에 존재하는지 확인합니다. 지원되는 변수의 제약 사항을 참고합니다.
• .gitlab-ci.yml에 environment:deployment_tier가 있다면, 값이 지원되는 티어인 production, staging, testing, development, other 중 하나인지 확인합니다.

리뷰 앱에서 이 오류가 발생하는 경우#

예를 들어 .gitlab-ci.yml에 다음 내용이 있다고 가정합니다.

review:
  script: deploy review app
  environment: review/$CI_COMMIT_REF_NAME

브랜치 이름이 bug-fix! 인 머지 리퀘스트를 새로 생성하면 review job은 review/bug-fix!라는 환경을 생성하려고 시도합니다. 그러나 !는 환경에 사용할 수 없는 문자이므로, 배포 job은 환경 없이 실행되는 상황이 되어 실패합니다.

이 문제는 다음 방법 중 하나로 해결합니다.

• bug-fix처럼 유효하지 않은 문자를 제외하고 기능 브랜치를 다시 생성합니다.

• CI_COMMIT_REF_NAME 사전 정의 변수를 유효하지 않은 문자를 제거하는 CI_COMMIT_REF_SLUG로 바꿉니다.

  review:
    script: deploy review app
    environment: review/$CI_COMMIT_REF_SLUG