Environments

GitLab의 환경(Environment)은 애플리케이션의 특정 배포 대상을 나타내요. development, staging, production 같은 것이죠. 소프트웨어 수명 주기의 각 단계에서 다른 구성을 관리하고 코드를 배포하는 데 사용합니다. 환경을 쓰면 배포 과정을 일관되고 반복 가능하게 유지하고, 어떤 코드가 어디에 배포됐는지 추적하고, 문제가 생기면 이전 버전으로 롤백할 수 있어요.

출처: 문서

본문

GitLab 환경은 애플리케이션의 특정 배포 대상을 나타내며, development, staging, production 같은 것들이 있어요. 소프트웨어 수명 주기의 다양한 단계에서 다른 구성을 관리하고 코드를 배포하는 데 사용합니다.

환경을 사용하면 여러분은:

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

환경과 배포 보기

전제 조건:

프라이빗 프로젝트에서는 Reporter, Developer, Maintainer, 또는 Owner 역할이 있어야 합니다. 환경 권한을 참고하세요.

주어진 프로젝트의 환경 목록은 여러 가지 방법으로 볼 수 있어요.

프로젝트 개요 페이지에서, 사용 가능한(즉, 중지되지 않은) 환경이 하나 이상 있으면.
왼쪽 사이드바에서 Operate > Environments를 선택합니다. 환경이 표시돼요.
환경의 배포 목록을 보려면 환경 이름을 선택하세요. 예를 들어 staging. 배포는 배포 잡이 만든 후에만 이 목록에 나타납니다.
배포 파이프라인의 모든 수동 잡 목록을 보려면 Run(플레이) 드롭다운 목록을 선택하세요.

환경 URL

환경 URL은 GitLab의 몇몇 곳에 표시됩니다.

머지 리퀘스트에서 링크로:
Environments 뷰에서 버튼으로:
Deployments 뷰에서 버튼으로:

다음 경우에 머지 리퀘스트에서 이 정보를 볼 수 있어요.

머지 리퀘스트가 결국 기본 브랜치(보통 main)로 머지될 때.
그 브랜치도 환경(예: staging 또는 production)에 배포할 때.

예를 들어:

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

GitLab Route Maps로 리뷰 앱용으로 설정된 환경에서 소스 파일에서 공개 페이지로 바로 이동할 수 있어요.

환경의 유형

환경은 static 또는 dynamic입니다.

Static 환경:

보통 연속된 배포가 재사용합니다.
staging이나 production 같은 정적 이름을 가져요.
수동으로 또는 CI/CD 파이프라인의 일부로 생성됩니다.

Dynamic 환경:

보통 CI/CD 파이프라인에서 생성되며 단일 배포에만 사용된 후 중지되거나 삭제됩니다.
보통 CI/CD 변수 값을 기반으로 하는 동적 이름을 가져요.
리뷰 앱의 기능입니다.

환경은 stop 잡이 실행됐는지에 따라 세 가지 상태 중 하나를 가집니다.

available: 환경이 존재합니다. 배포가 있을 수 있어요.
stopping: on stop 잡이 시작됨. on stop 잡이 정의되지 않았으면 이 상태는 적용되지 않습니다.
stopped: on stop 잡이 실행되었거나 사용자가 수동으로 잡을 중지함.

Static 환경 생성하기

UI 또는 .gitlab-ci.yml 파일에서 static 환경을 만들 수 있어요.

UI에서

전제 조건:

Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

UI에서 static 환경을 만들려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Operate > Environments를 선택하세요.
Create an environment을 선택합니다.
필드를 채웁니다.
Save를 선택하세요.

`.gitlab-ci.yml` 파일에서

전제 조건:

Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

.gitlab-ci.yml 파일에서 static 환경을 만들려면:

deploy 스테이지에 잡을 정의합니다.
잡에서 환경 name과 url을 정의하세요. 파이프라인이 실행될 때 그 이름의 환경이 존재하지 않으면 생성됩니다.

환경 이름에는 사용할 수 없는 일부 문자가 있습니다. environment 키워드에 대한 자세한 내용은 .gitlab-ci.yml 키워드 참조를 참고하세요.

예를 들어 URL https://staging.example.com에 staging이라는 환경을 만들려면:

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

Dynamic 환경 생성하기

dynamic 환경을 만들려면 각 파이프라인에 고유한 CI/CD 변수를 사용합니다.

전제 조건:

Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

.gitlab-ci.yml 파일에서 dynamic 환경을 만들려면:

deploy 스테이지에 잡을 정의합니다.
잡에서 다음 환경 속성을 정의합니다. name: $CI_COMMIT_REF_SLUG 같은 관련 CI/CD 변수를 사용합니다. 선택 사항으로 환경 이름에 정적 접두사를 추가하면 UI에서 같은 접두사를 가진 모든 환경을 그룹화합니다. url: 선택 사항. $CI_ENVIRONMENT_SLUG 같은 관련 CI/CD 변수로 호스트 이름 앞에 접두사를 붙입니다.

환경 이름에는 사용할 수 없는 일부 문자가 있습니다. environment 키워드에 대한 자세한 내용은 .gitlab-ci.yml 키워드 참조를 참고하세요.

다음 예시에서 deploy_review_app 잡이 실행될 때마다 환경의 이름과 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

Dynamic 환경 URL 설정

일부 외부 호스팅 플랫폼은 배포마다 https://94dd65b.amazonaws.com/qa-lambda-1234567 같은 임의의 URL을 생성해요. 이러면 .gitlab-ci.yml 파일에서 그 URL을 참조하기 어려워집니다.

배포 잡이 생성된 URL을 dotenv 변수로 캡처해 environment:url에 전달하도록 구성할 수 있어요. 잡에 artifacts:reports:dotenv를 지정하세요. 잡이 끝나면 GitLab이 dotenv 보고서를 파싱하고 environment:url을 변수 값으로 확장합니다. 할당된 URL은 그 후 UI에 표시됩니다.

정적 접두사와 변수를 결합할 수도 있어요. 예를 들어 https://$DYNAMIC_ENVIRONMENT_URL. DYNAMIC_ENVIRONMENT_URL이 example.com이면 결과는 https://example.com입니다.

개요는 잡이 끝난 후 동적 URL 설정 영상을 참고하세요.

다음 예시에서 리뷰 앱이 각 머지 리퀘스트에 대해 새 환경을 만듭니다.

review 잡은 모든 푸시에 의해 트리거되고, review/your-branch-name이라는 환경을 만들거나 업데이트합니다. 환경 URL은 $DYNAMIC_ENVIRONMENT_URL로 설정됩니다.
review 잡이 끝나면 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 잡에 environment:url을 설정하면 안 돼요.
환경 URL이 유효하지 않으면(예: 잘못된 형식의 URL) 시스템이 환경 URL을 업데이트하지 않습니다.
stop_review에서 실행되는 스크립트가 저장소에만 존재해서 GIT_STRATEGY: none 또는 GIT_STRATEGY: empty를 사용할 수 없다면, 이 잡에 대해 머지 리퀘스트 파이프라인을 구성하세요. 이렇게 하면 기능 브랜치가 삭제된 후에도 러너가 저장소를 가져올 수 있습니다. 자세한 내용은 러너용 Ref Specs를 참고하세요.

Windows 러너에서는 PowerShell Add-Content 명령을 사용해 .env 파일에 쓰세요.

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

환경의 배포 티어

같은 그룹의 프로젝트는 같은 배포 티어에 대해 서로 다른 환경 이름을 사용할 수 있어요. 예를 들어 한 프로젝트는 production을, 다른 프로젝트는 같은 티어에 custom-portal을 사용할 수 있습니다. 그룹 protected 환경은 이런 차이를 처리하기 위해 배포 티어를 사용합니다.

사용 가능한 배포 티어는 다음과 같습니다.

development
testing
staging
production
other

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

Ruby Regexp 패턴	배포 티어
`/(dev	review
`/(test	tst
`/(st(a	)g
`/(pr(o	)d

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

자동 추측을 피하려면 deployment_tier 키워드를 사용하세요.

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

환경 이름 바꾸기

환경은 이름을 바꿀 수 없습니다.

이름을 바꾸는 것과 같은 결과를 얻으려면:

CI/CD 변수

환경과 배포를 커스터마이즈하려면 사전 정의 CI/CD 변수를 사용할 수 있고, 커스텀 CI/CD 변수를 정의할 수도 있어요.

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

기본적으로 모든 CI/CD 변수는 파이프라인의 모든 잡에 제공됩니다. 잡의 테스트 도구가 손상되면 그 도구가 잡에 제공되는 모든 CI/CD 변수를 가져오려 시도할 수 있어요. 이런 종류의 공급망 공격을 완화하려면 민감한 변수의 환경 범위를 이를 필요로 하는 잡으로만 제한해야 합니다.

CI/CD 변수의 환경 범위를 제한하려면 변수가 사용 가능한 환경을 정의합니다. 기본 환경 범위는 * 와일드카드라서 어떤 잡이든 변수에 접근할 수 있어요.

특정 환경을 선택하려면 특정 일치(specific matching)를 사용할 수 있습니다. 예를 들어 변수의 환경 범위를 production으로 설정하면 환경이 production인 잡만 변수에 접근하도록 허용합니다.

와일드카드 일치(*)를 사용해 특정 환경 그룹, 예를 들어 review/*로 리뷰 앱 전체를 선택할 수도 있어요.

예를 들어 네 개의 환경이 있다면:

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

이 환경 범위들은 다음과 같이 일치합니다.

↓ 범위 / 환경 →	`production`	`staging`	`review/feature-1`	`review/feature-2`
`*`	일치	일치	일치	일치
`production`	일치
`staging`		일치
`review/*`			일치	일치
`review/feature-1`			일치

환경 범위 변수를 rules 또는 include와 함께 사용하면 안 돼요. 파이프라인 생성 시 GitLab이 파이프라인 구성을 검증할 때 변수가 정의되지 않았을 수 있기 때문입니다.

환경 검색

GitLab 17.4에서 일반 공개되었습니다. 기능 플래그 enable_environments_search_within_folder가 제거됐습니다.

이름으로 환경을 검색하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 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 동작으로 환경을 중지할 때, 잡이 아카이브되지 않았다면 실행됩니다.

UI로 환경 중지

Environments 뷰에서 on_stop 동작을 트리거하고 환경을 수동으로 중지하려면, stop 잡과 deploy 잡이 같은 resource_group에 있어야 합니다.

GitLab UI에서 환경을 중지하려면:

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

기본 중지 동작

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

하지만 이슈 428625은 production과 staging 환경이 명시적인 on_stop CI/CD 잡이 정의된 경우에만 중지되도록 이 동작을 바꾸는 것을 제안합니다.

환경의 중지 동작은 Environments API의 auto_stop_setting 파라미터로 구성할 수 있어요.

브랜치 삭제 시 환경 중지

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

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

두 잡 모두 같은 rules 또는 only/except 구성을 가져야 합니다. 그렇지 않으면 stop_review 잡이 deploy_review 잡을 포함하는 모든 파이프라인에 포함되지 않을 수 있고, action: stop을 트리거해 환경을 자동으로 중지할 수 없습니다.
action: stop이 있는 잡은 환경을 시작한 잡보다 나중 스테이지에 있으면 실행되지 않을 수 있어요.
머지 리퀘스트 파이프라인을 사용할 수 없다면, stop_review 잡에서 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 잡이 stop_review 잡을 호출해 환경을 정리하고 중지합니다.

Pipelines must succeed 설정이 켜져 있으면, stop_review 잡에 allow_failure: true 키워드를 구성해 파이프라인과 머지 리퀘스트를 막지 않게 할 수 있어요.

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

이 기능을 머지 트레인과 함께 사용하면, 중복 파이프라인이 방지된 경우에만 stop 잡이 실행됩니다.

특정 기간 후 환경 중지

환경이 특정 기간 후 자동으로 중지되도록 설정할 수 있어요.

리소스 제한으로 인해 환경을 중지하는 백그라운드 워커는 한 시간에 한 번만 실행됩니다. 즉 환경이 지정된 정확한 기간 후에 중지되지 않고, 백그라운드 워커가 만료된 환경을 감지할 때 중지될 수 있어요.

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

다음 예시에서:

머지 리퀘스트의 각 커밋은 환경에 최신 변경 사항을 배포하고 만료 기간을 재설정하는 review_app 잡을 실행합니다.
환경이 1주일 넘게 비활성 상태면 GitLab이 자동으로 stop_review_app 잡을 실행해 환경을 중지합니다.

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 키워드를 사용해 환경이 중지되도록 예약된 시간을 재설정할 수 있습니다. 자세한 내용은 준비 또는 검증 목적으로 환경 접근을 참고하세요.

환경의 예약 중지 날짜와 시간 보기

환경이 특정 기간 후 중지되도록 예약되면 만료 날짜와 시간을 볼 수 있어요.

환경의 만료 날짜와 시간을 보려면:

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

만료 날짜와 시간이 왼쪽 위 모서리, 환경 이름 옆에 표시됩니다.

환경의 예약 중지 날짜와 시간 재정의

환경이 특정 기간 후 중지되도록 예약되면 만료를 재정의할 수 있어요.

UI에서 환경 만료를 재정의하려면:

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

.gitlab-ci.yml에서 환경 만료를 재정의하려면:

프로젝트의 .gitlab-ci.yml을 엽니다.
해당 배포 잡의 auto_stop_in 설정을 auto_stop_in: never로 업데이트합니다.

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

오래된 환경 정리

프로젝트에서 오래된 환경을 중지하고 싶을 때 오래된 환경을 정리합니다.

전제 조건:

Maintainer 또는 Owner 역할이 있어야 합니다.

오래된 환경을 정리하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Operate > Environments를 선택하세요.
Clean up environments를 선택합니다.
어떤 환경을 오래된 것으로 간주할지 결정하는 날짜를 선택하세요.
Clean up을 선택합니다.

지정된 날짜 이후에 업데이트되지 않은 활성 환경이 중지됩니다. protected 환경은 무시되고 중지되지 않습니다.

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

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

환경의 배포 잡에 on_stop 동작으로 환경의 stop 잡을 정의할 수 있어요.

환경이 중지되면 최신 완료 파이프라인의 완료된 배포에 대한 stop 잡이 실행됩니다. 배포나 파이프라인은 successful, canceled, failed 상태면 완료된 것입니다.

전제 조건:

배포 잡과 stop 잡 모두 같은 rules 또는 only/except 구성을 가져야 합니다.
stop 잡에는 다음 키워드가 정의되어 있어야 합니다. when: 잡 수준 또는 rules 절 중 한 곳에서 정의. rules와 when: manual을 사용하면 잡이 실행되지 않아도 파이프라인이 완료될 수 있도록 allow_failure: true도 설정해야 해요. environment:name, environment:action

다음 예시에서:

review_app 잡이 첫 번째 잡이 끝난 후 stop_review_app 잡을 호출합니다.
stop_review_app은 when 아래에 정의된 내용을 기준으로 트리거됩니다. 이 경우 manual로 설정되어 있어 GitLab UI에서 수동 동작이 필요합니다.
GIT_STRATEGY는 none으로 설정됩니다. stop_review_app 잡이 자동으로 트리거되면 러너는 브랜치가 삭제된 후 코드를 체크아웃하려고 하지 않습니다.

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

환경에 대한 여러 stop 동작

환경에 여러 개의 병렬 stop 동작을 구성하려면 .gitlab-ci.yml 파일에 정의된 대로 같은 environment에 대해 여러 배포 잡에 on_stop 키워드를 지정하세요.

환경이 중지되면 성공한 배포 잡에서 온 일치하는 on_stop 동작만 특정 순서 없이 병렬로 실행됩니다.

환경의 모든 on_stop 동작은 같은 파이프라인에 속해야 합니다. 다운스트림 파이프라인에서 여러 on_stop 동작을 사용하려면 환경 동작을 부모 파이프라인에 구성해야 합니다. 자세한 내용은 배포를 위한 다운스트림 파이프라인을 참고하세요.

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

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` 동작을 실행하지 않고 환경 중지

정의된 on_stop 동작을 실행하지 않고 환경을 중지하고 싶을 때가 있을 수 있어요. 예를 들어 컴퓨트 쿼터를 사용하지 않고 많은 환경을 삭제하고 싶을 때요.

정의된 on_stop 동작을 실행하지 않고 환경을 중지하려면 force=true 파라미터로 환경 중지 API를 실행하세요.

환경 삭제

환경과 그 모든 배포를 제거하고 싶을 때 환경을 삭제합니다.

전제 조건:

Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.
환경을 삭제하려면 먼저 중지해야 합니다.

환경을 삭제하려면:

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

준비 또는 검증 목적으로 환경 접근

GitLab 17.7에서 prepare와 access 동작에 대해 auto_stop_in을 재설정하도록 업데이트되었습니다.

검증 또는 준비 같은 다양한 목적으로 환경에 접근하는 잡을 정의할 수 있어요. 이는 효과적으로 배포 생성을 우회하므로, CD 워크플로를 더 정확하게 조정할 수 있습니다.

이렇게 하려면 잡의 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

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

환경이 특정 기간 후 중지되도록 구성되어 있으면, access 또는 prepare 동작이 있는 잡이 예약된 중지 시간을 재설정합니다. 예약 시간을 재설정할 때 환경에 대한 가장 최근의 성공한 배포 잡의 environment:auto_stop_in이 사용됩니다. 예를 들어 가장 최근 배포가 auto_stop_in: 1 week를 사용했고 나중에 action: access가 있는 잡이 접근하면, 환경은 접근하는 잡이 완료된 시점으로부터 1주 후에 중지되도록 다시 예약됩니다.

예약된 중지 시간을 바꾸지 않고 환경에 접근하려면 verify 동작을 사용하세요.

환경 인시던트 관리

프로덕션 환경은 여러분의 통제 밖의 이유를 포함해 예기치 않게 다운될 수 있어요. 예를 들어 외부 의존성, 인프라, 또는 인적 오류 문제가 환경에 큰 문제를 일으킬 수 있습니다. 예를 들면:

의존하는 클라우드 서비스가 다운.
서드파티 라이브러리가 업데이트되어 애플리케이션과 호환되지 않음.
누군가 서버의 취약한 엔드포인트에 DDoS 공격.
운영자가 인프라를 잘못 구성.
프로덕션 애플리케이션 코드에 버그 도입.

인시던트 관리를 사용해 즉각적인 주의가 필요한 심각한 문제가 있을 때 알림을 받을 수 있어요.

환경에 대한 최신 알림 보기

알림 통합을 설정하면 환경에 대한 알림이 environments 페이지에 표시됩니다. 가장 심각도가 높은 알림이 표시되므로 어떤 환경에 즉각적인 주의가 필요한지 식별할 수 있어요.

알림을 트리거한 문제가 해결되면 알림은 제거되고 environments 페이지에 더 이상 표시되지 않습니다.

알림이 롤백을 요구한다면 환경 페이지에서 배포 탭을 선택하고 어떤 배포로 롤백할지 선택할 수 있어요.

자동 롤백 (Auto Rollback)

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

GitLab Auto Rollback은 심각한 알림이 감지되면 자동으로 롤백을 트리거해 이 워크플로를 완화해 줍니다. GitLab이 롤백에 적절한 환경을 선택하려면 알림에 환경 이름이 있는 gitlab_environment_name 키가 포함되어야 합니다. GitLab은 가장 최근의 성공한 배포를 선택해 재배포합니다.

GitLab Auto Rollback의 제한 사항:

알림이 감지될 때 배포가 실행 중이면 롤백이 건너뜁니다.
롤백은 3분에 한 번만 일어날 수 있습니다. 여러 알림이 한 번에 감지되면 하나의 롤백만 수행됩니다.

GitLab Auto Rollback은 기본적으로 꺼져 있습니다. 켜려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
Automatic deployment rollbacks을 펼칩니다.
Enable automatic rollbacks 체크박스를 선택합니다.
Save changes를 선택하세요.

환경 권한

역할에 따라 공개 및 프라이빗 프로젝트에서 환경과 상호작용할 수 있습니다.

환경 보기

공개 프로젝트에서는 멤버가 아닌 사람을 포함해 누구나 환경 목록을 볼 수 있습니다.
프라이빗 프로젝트에서는 환경 목록을 보려면 Reporter, Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

환경 생성 및 업데이트

새 환경을 만들거나 보호되지 않은 기존 환경을 업데이트하려면 Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.
Protected 환경의 경우 Allowed to deploy 목록에 있어야 합니다.

환경 중지 및 삭제

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

protected 환경에서 배포 잡 실행

protected 브랜치에 푸시하거나 머지할 수 있다면:

Reporter, Developer, Maintainer, 또는 Owner 역할이 있어야 합니다.

protected 브랜치에 푸시할 수 없다면:

Reporter 역할이 있는 그룹의 일원이어야 합니다.

protected 환경에 대한 배포 전용 접근을 참고하세요.

웹 터미널 (deprecated)

이 기능은 GitLab 14.5에서 deprecated되었습니다.

배포 서비스(예: Kubernetes 통합)의 도움으로 환경에 배포하면, GitLab이 환경에 터미널 세션을 열 수 있어요. 그러면 웹 브라우저를 떠나지 않고 문제를 디버깅할 수 있습니다.

웹 터미널은 컨테이너 기반 배포라서 편집기 같은 기본 도구가 없는 경우가 많고, 언제든 중지되거나 재시작될 수 있어요. 이런 일이 생기면 모든 변경 사항을 잃습니다. 웹 터미널을 포괄적인 온라인 IDE가 아닌 디버깅 도구로 취급하세요.

웹 터미널:

프로젝트 Maintainer와 Owner에게만 제공됩니다.
활성화되어 있어야 합니다.

UI에서 웹 터미널을 보려면 다음 중 하나를 하세요.

Actions 메뉴에서 Terminal을 선택합니다:
특정 환경 페이지에서 오른쪽의 Terminal(터미널)을 선택합니다.

버튼을 선택해 터미널 세션을 시작하세요. 다른 터미널처럼 동작합니다. 여러분은 배포가 만든 컨테이너 안에 있으므로 다음을 할 수 있어요.

셸 명령을 실행하고 실시간 응답을 받기.
로그 확인.
구성이나 코드 변경 시도.

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

문제 해결

`action: stop`이 있는 잡이 실행되지 않음

어떤 경우에는 on_stop 잡이 구성되어 있어도 환경이 중지되지 않습니다. 이는 action: stop이 있는 잡이 stages: 또는 needs: 구성 때문에 실행 가능한 상태가 아닐 때 발생해요.

예를 들어:

환경이 실패한 잡도 있는 스테이지에서 시작할 수 있습니다. 그러면 이후 스테이지의 잡이 시작되지 않아요. 환경의 action: stop 잡이 이후 스테이지에 있어도 시작할 수 없어 환경이 삭제되지 않습니다.
action: stop이 있는 잡이 아직 완료되지 않은 잡에 의존할 수 있어요.

action: stop이 필요할 때 항상 실행되도록 하려면:

두 잡을 같은 스테이지에 둡니다.

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 잡에 needs 항목을 추가해 스테이지 순서 밖에서 시작할 수 있게 합니다.

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`

프로젝트가 dynamic 환경을 생성하도록 구성되어 있다면, 동적으로 생성된 파라미터가 환경 생성에 사용될 수 없어서 배포 잡에서 이 오류를 만날 수 있어요.

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/이라는 이름의 환경을 만들려고 시도합니다.

이를 고치려면 다음 해결 방법 중 하나를 사용하세요.

배포 잡에서 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 잡이 review/bug-fix! 환경을 만들려고 합니다. 하지만 !는 환경에 유효하지 않은 문자이므로, 배포 잡이 환경 없이 실행되려다 실패합니다.

이를 고치려면 다음 해결 방법 중 하나를 사용하세요.

유효하지 않은 문자가 없는 기능 브랜치를 다시 만듭니다. 예: bug-fix.
CI_COMMIT_REF_NAME 사전 정의 변수를 유효하지 않은 문자를 제거하는 CI_COMMIT_REF_SLUG로 바꿉니다.

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

더 알아보기

환경은 static/dynamic 두 종류가 있고, dynamic 환경은 리뷰 앱과 연결돼요. 배포 추적, 환경 범위 변수, on_stop을 통한 자동 정리를 이해하는 것이 핵심이에요. 다음으로는 배포(Deployments) 문서로 배포 이력과 롤백을, 배포 안전 문서로 protected 환경과 동시 배포 방지를 함께 익혀 두면 운영이 안정적입니다.

Environments

Environments

본문

환경과 배포 보기

환경 URL

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

환경의 유형

Static 환경 생성하기

UI에서

.gitlab-ci.yml 파일에서

Dynamic 환경 생성하기

Dynamic 환경 URL 설정

환경의 배포 티어

환경 이름 바꾸기

CI/CD 변수

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

환경 검색

유사한 환경 그룹화

환경 중지하기

UI로 환경 중지

기본 중지 동작

브랜치 삭제 시 환경 중지

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

특정 기간 후 환경 중지

환경의 예약 중지 날짜와 시간 보기

환경의 예약 중지 날짜와 시간 재정의

오래된 환경 정리

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

환경에 대한 여러 stop 동작

on_stop 동작을 실행하지 않고 환경 중지

환경 삭제

준비 또는 검증 목적으로 환경 접근

환경 인시던트 관리

환경에 대한 최신 알림 보기

자동 롤백 (Auto Rollback)

환경 권한

환경 보기

환경 생성 및 업데이트

환경 중지 및 삭제

protected 환경에서 배포 잡 실행

웹 터미널 (deprecated)

관련 주제

문제 해결

action: stop이 있는 잡이 실행되지 않음

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

리뷰 앱에서 이 오류가 날 때

더 알아보기

`.gitlab-ci.yml` 파일에서

`on_stop` 동작을 실행하지 않고 환경 중지

`action: stop`이 있는 잡이 실행되지 않음

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