보호된 환경

보호된 환경 (Protected environments)

환경(Environments)은 테스트와 프로덕션 용도로 모두 사용할 수 있어요. 배포 잡은 서로 다른 역할을 가진 여러 사용자가 실행할 수 있기 때문에, 권한이 없는 사용자의 영향으로부터 특정 환경을 보호하는 것이 중요해요.

기본적으로 보호된 환경은 적절한 권한이 있는 사람만 배포할 수 있도록 보장해서 환경을 안전하게 지켜줘요. GitLab 관리자는 보호된 환경을 포함한 모든 환경을 사용할 수 있어요.

환경을 보호하거나 보호를 해제하려면 최소한 Maintainer 역할이 필요해요. 또한 external_url, tier, description 같은 환경 속성을 업데이트하려면 Allowed to deploy 목록에도 있어야 해요.

보호된 환경은 CI/CD 설정의 일부예요. 프로젝트에서 CI/CD가 꺼져 있으면 보호된 환경은 UI와 API를 통해 사용할 수 없어요. 이때 API는 모든 요청(보호된 환경 나열 포함)에 대해 403 Forbidden을 반환해요.

출처: 문서

본문

환경 보호하기

전제 조건:

• 승인자 그룹에 Allowed to deploy 권한을 부여할 때, 보호된 환경을 구성하는 사용자가 승인자 그룹의 직접 멤버여야 목록에 추가할 수 있어요. 그렇지 않으면 그룹이나 하위 그룹이 드롭다운 목록에 나타나지 않아요. 자세한 내용은 issue #345140을 참고해요.

• 승인자 그룹이나 프로젝트에 Approvers 권한을 부여할 때, 기본적으로 승인자 그룹이나 프로젝트의 직접 멤버만 이 권한을 받아요. 승인자 그룹이나 프로젝트의 상속된 멤버에게도 이 권한을 부여하려면:

  • Enable group inheritance 체크박스를 선택해요.
  • API를 사용해요.

환경을 보호하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾아요.

2. 왼쪽 사이드바에서 Settings > CI/CD를 선택해요.

3. Protected environments를 펼쳐요.

4. Protect an environment를 선택해요.

5. Environment 목록에서 보호하려는 환경을 선택해요.

6. Allowed to deploy 목록에서 배포 접근 권한을 부여할 역할, 사용자 또는 그룹을 선택해요. 다음을 기억해 두세요.

   • 두 가지 역할 중에서 선택할 수 있어요.

     • Maintainers: 프로젝트의 Maintainer 역할을 가진 모든 사용자에게 접근 허용.
     • Developers: 프로젝트의 Maintainer와 Developer 역할을 가진 모든 사용자에게 접근 허용.

   • 이미 프로젝트에 초대된 그룹을 선택할 수도 있어요. Reporter 역할로 프로젝트에 추가된 초대 그룹은 배포 전용 접근을 위한 드롭다운 목록에 나타나요.

   • 특정 사용자를 선택할 수도 있어요. Allowed to deploy 목록에 나타나려면 사용자가 Developer, Maintainer 또는 Owner 역할이 있어야 해요.

7. Approvers 목록에서 배포 접근 권한을 부여할 역할, 사용자 또는 그룹을 선택해요. 다음을 기억해 두세요.

   • 두 가지 역할 중에서 선택할 수 있어요.

     • Maintainers: 프로젝트의 Maintainer 역할을 가진 모든 사용자에게 접근 허용.
     • Developers: 프로젝트의 Maintainer와 Developer 역할을 가진 모든 사용자에게 접근 허용.

   • 이미 프로젝트에 초대된 그룹만 선택할 수 있어요.

   • Approvers 목록에 나타나려면 사용자가 Developer, Maintainer 또는 Owner 역할이 있어야 해요.

8. Approval rules 섹션에서:

   • 이 숫자가 규칙의 멤버 수보다 작거나 같은지 확인해요.
   • 이 기능에 대한 자세한 내용은 배포 승인(Deployment Approvals)을 참고해요.

9. Protect를 선택해요.

보호된 환경이 이제 보호된 환경 목록에 나타나요.

API로 환경 보호하기

또는 API를 사용해 환경을 보호할 수도 있어요.

1. 환경을 만드는 CI가 있는 프로젝트를 사용해요. 예를 들어:

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - 'echo "Testing Application: ${CI_PROJECT_NAME}"'

production:
  stage: deploy
  when: manual
  script:
    - 'echo "Deploying to ${CI_ENVIRONMENT_NAME}"'
  environment:
    name: ${CI_JOB_NAME}

2. UI로 새 그룹을 만들어요. 예를 들어 이 그룹은 protected-access-group이라고 하고 그룹 ID는 9899826이에요. 이 단계의 나머지 예시들은 이 그룹을 사용한다는 점에 유의해요.

3. API를 사용해 사용자를 그룹에 reporter로 추가해요.

$ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --data "user_id=3222377&access_level=20" "https://gitlab.com/api/v4/groups/9899826/members"

{"id":3222377,"name":"Sean Carroll","username":"sfcarroll","state":"active","avatar_url":"https://gitlab.com/uploads/-/system/user/avatar/3222377/avatar.png","web_url":"https://gitlab.com/sfcarroll","access_level":20,"created_at":"2020-10-26T17:37:50.309Z","expires_at":null}

4. API를 사용해 그룹을 프로젝트에 reporter로 추가해요.

$ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
       --request POST "https://gitlab.com/api/v4/projects/22034114/share?group_id=9899826&group_access=20"

{"id":1233335,"project_id":22034114,"group_id":9899826,"group_access":20,"expires_at":null}

5. API를 사용해 보호된 환경 접근 권한으로 그룹을 추가해요.

curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.com/api/v4/projects/22034114/protected_environments"

이제 그룹에 접근 권한이 생기고 UI에서 볼 수 있어요.

그룹 멤버십으로 환경 접근하기

사용자는 그룹 멤버십의 일부로 보호된 환경에 대한 접근 권한을 얻을 수 있어요. Reporter 역할의 사용자는 이 방법으로만 보호된 환경에 대한 접근 권한을 부여받을 수 있어요.

배포 브랜치 접근

Developer 역할의 사용자는 다음 방법 중 하나로 보호된 환경에 대한 접근 권한을 얻을 수 있어요.

• 개인 기여자로서, 역할을 통해.
• 그룹 멤버십을 통해.

사용자가 프로덕션에 배포된 브랜치에 대한 push 또는 merge 접근 권한도 있다면 다음 권한을 가져요.

• 환경 중지.
• 환경 삭제.
• 환경 터미널 만들기.

보호된 환경에 대한 배포 전용 접근

보호된 환경에 대한 접근 권한은 있지만, 배포되는 브랜치에 대한 push 또는 merge 접근 권한이 없는 사용자는 환경 배포에만 접근할 수 있어요. Reporter 역할로 프로젝트에 추가된 초대 그룹은 배포 전용 접근을 위한 드롭다운 목록에 나타나요.

배포 전용 접근을 추가하려면:

1. 아직 없다면 보호된 환경에 대한 접근 권한을 가진 멤버로 그룹을 만들어요.
2. 그룹을 Reporter 역할로 프로젝트에 초대해요.
3. 환경 보호하기의 단계를 따라요.

환경 수정 및 보호 해제

Maintainer는 다음을 할 수 있어요.

• Allowed to deploy 목록과 승인 규칙을 포함한 보호 설정을 언제든 업데이트.
• 해당 환경에 대해 Unprotect를 선택해 보호된 환경의 보호를 해제.

보호된 환경에서 external_url, tier, description 같은 환경 속성을 업데이트하려면 사용자가 Allowed to deploy 목록에도 있어야 해요.

환경 보호가 해제되면 모든 접근 항목이 삭제되고, 환경을 다시 보호하면 다시 입력해야 해요.

승인 규칙이 삭제된 후에는 이전에 승인된 배포가 누가 배포를 승인했는지 표시하지 않아요. 배포를 승인한 사람에 대한 정보는 프로젝트 감사 이벤트에서 계속 확인할 수 있어요. 새 규칙이 추가되면 이전 배포는 배포 승인 옵션 없이 새 규칙을 표시해요. Issue 506687은 승인 규칙이 삭제되어도 배포의 전체 승인 기록을 표시하는 것을 제안하고 있어요.

자세한 내용은 배포 안전성을 참고해요.

그룹을 위한 보호된 환경

일반적으로 대기업 조직은 개발자와 운영자 사이에 명시적인 권한 경계가 있어요. 개발자는 코드를 빌드하고 테스트하며, 운영자는 애플리케이션을 배포하고 모니터링해요. 그룹을 위한 보호된 환경을 사용하면 운영자가 개발자로부터 중요 환경에 대한 접근을 제한할 수 있어요. 이는 프로젝트를 위한 보호된 환경을 그룹으로 확장한 것이에요.

배포 권한은 다음 표로 설명할 수 있어요.

환경	개발자	운영자	범주
Development	허용	허용	하위(lower) 환경
Testing	허용	허용	하위 환경
Staging	거부	허용	상위(higher) 환경
Production	거부	허용	상위 환경

(참조: 위키백과의 배포 환경)

그룹을 위한 보호된 환경 이름

프로젝트를 위한 보호된 환경과 달리, 그룹을 위한 보호된 환경은 이름으로 배포 티어(deployment tier)를 사용해요.

그룹은 고유한 이름을 가진 여러 프로젝트 환경으로 구성될 수 있어요. 예를 들어 Project-A에는 gprd 환경이 있고 Project-B에는 Production 환경이 있다면, 특정 환경 이름을 보호하는 것은 확장이 잘 되지 않아요. 배포 티어를 사용하면 둘 다 production 배포 티어로 인식되고 동시에 보호돼요.

그룹 멤버십 구성하기

그룹을 위한 보호된 환경의 효과를 최대화하려면 그룹 멤버십을 올바르게 구성해야 해요.

• 운영자에게는 최상위 그룹에 대한 Owner 역할을 부여해야 해요. 운영자는 그룹 설정 페이지에서 상위 환경(예: production)의 CI/CD 구성을 관리할 수 있어요. 여기에는 그룹을 위한 보호된 환경, 그룹을 위한 러너, 그룹을 위한 클러스터가 포함돼요. 이러한 구성은 읽기 전용 항목으로 하위 프로젝트에 상속돼요. 이렇게 해야 운영자만 조직 전체 배포 규칙을 구성할 수 있어요.

• 개발자에게는 최상위 그룹에 대해 Developer 역할을 넘지 않는 권한을 부여하거나, 하위 프로젝트에 대해 Owner 역할을 명시적으로 부여해야 해요. 개발자는 최상위 그룹의 CI/CD 구성에 접근할 수 없으므로, 운영자는 중요 구성이 개발자에 의해 실수로 변경되지 않도록 보장할 수 있어요.

• 하위 그룹과 하위 프로젝트에 대해:

  • 부모 그룹이 자신을 위해 보호된 환경을 구성했다면, 그 하위 그룹은 이를 재정의할 수 없어요.
  • 프로젝트를 위한 보호된 환경은 그룹 설정과 결합할 수 있어요. 두 구성이 모두 존재하면 배포 잡을 실행하려면 사용자가 두 규칙 세트에서 모두 허용되어야 해요.
  • 최상위 그룹의 프로젝트나 하위 그룹에서 개발자는 하위 환경(예: testing)을 조정하기 위해 Maintainer 역할을 안전하게 할당받을 수 있어요.

이 구성이 갖춰지면:

• 사용자가 프로젝트에서 배포 잡을 실행하려 하고 환경에 배포가 허용되어 있으면, 배포 잡이 진행돼요.
• 사용자가 프로젝트에서 배포 잡을 실행하려 하지만 환경에 배포가 허용되어 있지 않으면, 배포 잡은 오류 메시지와 함께 실패해요.

그룹 아래에서 중요 환경 보호하기

그룹을 위해 환경을 보호하려면 환경이 .gitlab-ci.yml에 올바른 [deployment_tier](/ci/environments/#deployment-tier-of-environments)를 정의했는지 확인해요.

UI 사용하기

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾아요.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택해요.
3. Protected environments를 펼쳐요.
4. Environment 목록에서 보호하려는 환경 배포 티어를 선택해요.
5. Allowed to deploy 목록에서 배포 접근 권한을 부여할 하위 그룹을 선택해요.
6. Protect를 선택해요.

API 사용하기

REST API를 사용해 그룹을 위한 보호된 환경을 구성해요.

배포 승인 (Deployment approvals)

보호된 환경은 배포 전에 수동 승인을 요구하는 데에도 사용할 수 있어요. 자세한 내용은 배포 승인을 참고해요.

문제 해결

Reporter가 하위 파이프라인에서 보호된 환경에 배포하는 트리거 잡을 실행할 수 없음

[trigger](/ci/yaml/#trigger) 키워드를 사용하는 잡은 보호된 환경에 대한 배포 전용 접근이 있어도 실행되지 않을 수 있어요.

이 문제는 트리거 잡에 [environment](/ci/yaml/#environment) 키워드가 설정되지 않았을 때 발생해요. 이것이 없으면 GitLab이 잡을 보호된 환경과 연결할 수 없어서, 잡이 사용자의 배포 전용 역할 접근을 허용하지 않는 일반 CI/CD 권한 모델로 대체되기 때문이에요.

이 문제를 해결하려면 트리거 잡에 environment 키워드를 직접 추가해요.

더 알아보기

보호된 환경은 배포 안전성과 승인 흐름의 핵심이에요. 배포 승인을 구성하는 방법은 배포 승인 문서를, 배포 안전성 전반은 배포 안전성 문서를 함께 읽어보는 걸 추천해요.