중요한 마일스톤에서 프로젝트를 패키징하려면 릴리스를 생성합니다. 릴리스는 코드, 바이너리, 문서, 릴리스 노트를 프로젝트의 완전한 스냅샷 하나로 묶습니다. 릴리스를 생성하면 GitLab 이 코드에 자동으로 태그를 지정하고, 스냅샷을 아카이브하고, 감사에 바로 쓸 수 있는 증거를 생성합니다. 이렇게 만들어진 영구 기록은 규정 준수 요구 사항에 완벽하게 맞고, 사용자가 개발 프로세스를 신뢰하게 만듭니다.

사용자는 다음과 같은 이점을 얻습니다.

• 최신 안정 버전과 설치 패키지에 손쉽게 액세스
• 새 기능과 수정 사항에 관한 명확한 문서
• 해당 에셋과 함께 특정 버전을 다운로드하는 기능
• 시간 경과에 따른 프로젝트의 변화를 간단하게 추적하는 방법

릴리스를 생성할 때 또는 생성한 뒤에 다음을 할 수 있습니다.

• 릴리스 노트를 추가합니다.
• 릴리스에 연결된 Git 태그의 메시지를 추가합니다.
• 릴리스에 마일스톤을 연결합니다.
• 런북이나 패키지 같은 릴리스 에셋을 첨부합니다.

릴리스 보기#

릴리스 목록을 보는 방법은 다음과 같습니다.

• 왼쪽 사이드바에서 Deploy > Releases를 선택합니다. 또는

• 프로젝트 개요 페이지에 릴리스가 하나 이상 있으면 릴리스 개수를 선택합니다.

  

  • 공개 프로젝트에서는 이 숫자가 모든 사용자에게 표시됩니다.
  • 비공개 프로젝트에서는 이 숫자가 최소 Reporter 권한이 있는 사용자에게 표시됩니다.

릴리스 정렬#

릴리스를 Released date 또는 Created date로 정렬하려면 정렬 순서 드롭다운 목록에서 선택합니다. 오름차순과 내림차순을 전환하려면 Sort order를 선택합니다.

최신 릴리스로 가는 영구 링크#

영구 링크로 최신 릴리스 페이지에 액세스할 수 있습니다. GitLab은 영구 링크 URL을 항상 최신 릴리스 페이지의 주소로 리다이렉트합니다.

URL 형식은 다음과 같습니다.

https://gitlab.example.com/namespace/project/-/releases/permalink/latest

영구 링크 URL에 접미사를 추가할 수도 있습니다. 예를 들어 gitlab-org 네임스페이스의 gitlab-runner 프로젝트에서 최신 릴리스가 v17.7.0#release 라면, 읽을 수 있는 링크는 다음과 같습니다.

https://gitlab.com/gitlab-org/gitlab-runner/-/releases/v17.7.0#release

다음 영구 링크로 최신 릴리스 URL에 액세스할 수 있습니다.

https://gitlab.com/gitlab-org/gitlab-runner/-/releases/permalink/latest#release

릴리스 에셋에 영구 링크를 추가하는 방법은 최신 릴리스 에셋으로 가는 영구 링크를 참고합니다.

정렬 기본 설정#

GitLab은 기본적으로 released_at 시간을 사용해 릴리스를 가져옵니다. 쿼리 파라미터 ?order_by=released_at 사용은 선택 사항이며, ?order_by=semver 지원은 이 이슈에서 추적합니다.

RSS 피드로 릴리스 추적#

GitLab은 프로젝트 릴리스의 RSS 피드를 제공합니다. 피드를 보는 방법은 다음과 같습니다.

1. 멤버로 참여한 프로젝트의 경우:
   1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
   2. Deploy > Releases를 선택합니다.
2. 모든 프로젝트의 경우:
   1. Project overview 페이지로 이동합니다.
   2. 오른쪽 사이드바에서 Releases ([rocket-launch])를 선택합니다.
3. 오른쪽 상단에서 피드 기호 ([rss])를 선택합니다.

릴리스 생성#

릴리스는 다음 방법으로 생성할 수 있습니다.

• CI/CD 파이프라인의 job 사용.
• Releases 페이지에서 생성.
• Releases API 사용.

Releases 페이지에서 릴리스 생성#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다. 자세한 내용은 릴리스 권한을 참고합니다.

Releases 페이지에서 릴리스를 생성하는 방법은 다음과 같습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Releases를 선택하고 New release를 선택합니다.
3. Tag name 드롭다운 목록에서 다음 중 하나를 수행합니다.
   • 기존 Git 태그를 선택합니다. 이미 릴리스에 연결된 기존 태그를 선택하면 검증 오류가 발생합니다.
   • 새 Git 태그 이름을 입력합니다.
     1. Create tag 팝오버에서 새 태그를 생성할 때 사용할 브랜치나 커밋 SHA를 선택합니다.
     2. 선택 사항. Set tag message 텍스트 상자에 주석 태그를 생성할 메시지를 입력합니다.
     3. Save를 선택합니다.
4. 선택 사항. 릴리스에 관한 다음 추가 정보를 입력합니다.
   • Title.
   • Milestones.
   • Release notes.
   • Tag message 포함 여부.
   • Asset links.
5. Create release를 선택합니다.

CI/CD job을 사용한 릴리스 생성#

job 정의에서 release 키워드를 사용해 GitLab CI/CD 파이프라인의 일부로 릴리스를 직접 생성할 수 있습니다. 릴리스 생성은 CI/CD 파이프라인의 마지막 단계 중 하나로 두는 편이 좋습니다.

릴리스는 job 이 오류 없이 처리될 때만 생성됩니다. 릴리스 생성 중에 API가 오류를 반환하면 릴리스 job 이 실패합니다.

다음 링크는 CI/CD job으로 릴리스를 생성하는 대표적인 구성 예시를 보여 줍니다.

• Git 태그가 생성될 때 릴리스 생성.
• 커밋이 기본 브랜치에 머지될 때 릴리스 생성.
• 커스텀 스크립트에서 릴리스 메타데이터 생성.

커스텀 SSL CA 인증 기관 사용#

ADDITIONAL_CA_CERT_BUNDLE CI/CD 변수로 커스텀 SSL CA 인증 기관을 구성할 수 있습니다. 이 인증 기관은 glab CLI가 커스텀 인증서를 사용하는 HTTPS로 API를 통해 릴리스를 생성할 때 피어를 검증하는 데 쓰입니다. ADDITIONAL_CA_CERT_BUNDLE 값에는 X.509 PEM 공개 키 인증서의 텍스트 표현이나 인증 기관이 담긴 path/to/file을 넣습니다. 예를 들어 .gitlab-ci.yml 파일에서 이 값을 구성하려면 다음과 같이 작성합니다.

release:
  variables:
    ADDITIONAL_CA_CERT_BUNDLE: |
        -----BEGIN CERTIFICATE-----
        MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
        ...
        jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
        -----END CERTIFICATE-----
  script:
    - echo "Create release"
  release:
    name: 'My awesome release'
    tag_name: '$CI_COMMIT_TAG'

ADDITIONAL_CA_CERT_BUNDLE 값은 UI의 커스텀 변수로도 구성할 수 있습니다. 인증서 경로가 필요한 file로 구성하거나, 인증서의 텍스트 표현이 필요한 변수로 구성합니다.

단일 파이프라인에서 여러 릴리스 생성#

하나의 파이프라인에 여러 release job을 둘 수 있습니다. 예:

ios-release:
  script:
    - echo "iOS release job"
  release:
    tag_name: v1.0.0-ios
    description: 'iOS release v1.0.0'

android-release:
  script:
    - echo "Android release job"
  release:
    tag_name: v1.0.0-android
    description: 'Android release v1.0.0'

릴리스 에셋을 Generic 패키지로 호스팅#

Generic 패키지를 사용해 릴리스 에셋을 호스팅할 수 있습니다.

패키징한 에셋으로 릴리스를 생성하는 방법은 다음과 같습니다.

1. CI/CD 파이프라인에서 패키지 파일을 빌드합니다.

2. glab CLI job으로 릴리스를 생성합니다.

   Create Release:
     stage: release
     image: registry.gitlab.com/gitlab-org/cli:latest
     rules:
       - if: $CI_COMMIT_TAG
     script:
       - |
         glab release create "$CI_COMMIT_TAG" \
         --name "Release ${VERSION}" \
         --notes "Your release notes here" \
         path/to/your/release-asset-file \
         --use-package-registry
   

   포함하려는 에셋마다 --assets-link 링크를 하나씩 더 추가합니다.

예정된 릴리스#

Releases API를 사용해 릴리스를 미리 생성할 수 있습니다. 미래의 released_at 날짜를 설정하면 릴리스 태그 옆에 Upcoming Release 배지가 표시됩니다. released_at 날짜와 시간이 지나면 배지는 자동으로 제거됩니다.

과거 릴리스#

Releases API 또는 UI를 사용해 과거 시점의 릴리스를 생성할 수 있습니다. 과거의 released_at 날짜를 설정하면 릴리스 태그 옆에 Historical release 배지가 표시됩니다. 과거에 릴리스된 것이므로 릴리스 증거는 사용할 수 없습니다.

릴리스 편집#

릴리스를 생성한 뒤 세부 정보를 편집하려면 릴리스 업데이트 API 또는 UI를 사용합니다.

사전 요구 사항:

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

UI에서 수행하는 방법은 다음과 같습니다.

1. 왼쪽 사이드바에서 Deploy > Releases를 선택합니다.
2. 수정하려는 릴리스의 오른쪽 상단에서 Edit this release (연필 아이콘)를 선택합니다.
3. Edit Release 페이지에서 릴리스의 세부 정보를 변경합니다.
4. Save changes를 선택합니다.

릴리스 삭제#

릴리스를 삭제하면 에셋도 함께 삭제됩니다. 그러나 연결된 Git 태그는 삭제되지 않습니다. 릴리스에 연결된 Git 태그를 삭제하면 릴리스도 삭제됩니다.

사전 요구 사항:

• Developer, Maintainer 또는 Owner 권한이 있어야 합니다. 릴리스 권한에서 자세한 내용을 확인합니다.

릴리스를 삭제하려면 릴리스 삭제 API 또는 UI를 사용합니다.

UI에서 수행하는 방법은 다음과 같습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Deploy > Releases를 선택합니다.
3. 삭제하려는 릴리스의 오른쪽 상단에서 Edit this release (✏️)를 선택합니다.
4. Edit Release 페이지에서 Delete를 선택합니다.
5. Delete release를 선택합니다.

릴리스에 마일스톤 연결#

릴리스를 하나 이상의 프로젝트 마일스톤에 연결할 수 있습니다.

GitLab Premium 고객은 릴리스에 연결할 그룹 마일스톤을 지정할 수 있습니다.

이 작업은 사용자 인터페이스에서 수행하거나, Releases API 요청에 milestones 배열을 포함해 수행할 수 있습니다.

사용자 인터페이스에서 릴리스에 마일스톤을 연결하는 방법은 다음과 같습니다.

1. 왼쪽 사이드바에서 Deploy > Releases를 선택합니다.
2. 수정하려는 릴리스의 오른쪽 상단에서 Edit this release (연필 아이콘)를 선택합니다.
3. Milestones 목록에서 연결할 마일스톤을 각각 선택합니다. 여러 마일스톤을 선택할 수 있습니다.
4. Save changes를 선택합니다.

Deploy > Releases 페이지의 상단 섹션에는 Milestone 이 마일스톤에 속한 이슈 통계와 함께 표시됩니다.

릴리스는 Plan > Milestones 페이지에서도, 그리고 이 페이지에서 마일스톤을 선택할 때도 확인할 수 있습니다.

다음은 릴리스가 없는 마일스톤, 릴리스가 하나인 마일스톤, 릴리스가 두 개인 마일스톤의 예입니다.

릴리스 생성 시 알림 받기#

프로젝트에 새 릴리스가 생성되면 이메일로 알림을 받을 수 있습니다.

릴리스 알림을 구독하는 방법은 다음과 같습니다.

1. 왼쪽 사이드바에서 Project overview를 선택합니다.
2. Notification setting (종 아이콘)을 선택합니다.
3. 목록에서 Custom을 선택합니다.
4. New release 체크박스를 선택합니다.
5. 대화 상자를 닫아 저장합니다.

배포 동결을 설정해 의도하지 않은 릴리스 방지#

배포 동결 기간을 설정하면 지정한 기간 동안 의도하지 않은 프로덕션 릴리스를 방지할 수 있습니다. 배포 동결은 배포를 자동화할 때 불확실성과 위험을 줄이는 데 도움이 됩니다.

Maintainer는 사용자 인터페이스에서 배포 동결 기간을 설정하거나, Freeze Periods API로 freeze_start와 freeze_end를 설정할 수 있습니다. 이 두 값은 crontab 항목으로 정의합니다.

실행 중인 job 이 동결 기간에 있으면 GitLab CI/CD는 $CI_DEPLOY_FREEZE라는 환경 변수를 생성합니다.

그룹 내 여러 프로젝트에서 배포 job 이 실행되지 않게 하려면 그룹 전체가 공유하는 파일에 .freezedeployment job을 정의합니다. includes 키워드를 사용해 프로젝트의 .gitlab-ci.yml 파일에 이 템플릿을 포함시킵니다.

.freezedeployment:
  stage: deploy
  before_script:
    - '[[ ! -z "$CI_DEPLOY_FREEZE" ]] && echo "INFRASTRUCTURE OUTAGE WINDOW" && exit 1; '
  rules:
    - if: '$CI_DEPLOY_FREEZE'
      when: manual
      allow_failure: true
    - when: on_success

배포 job 이 실행되지 않게 하려면 .gitlab-ci.yml 파일의 deploy_to_production job에서 extends 키워드를 사용해 .freezedeployment 템플릿 job의 구성을 상속합니다.

deploy_to_production:
  extends: .freezedeployment
  script: deploy_to_prod.sh
  environment: production

이 구성은 배포 job을 조건에 따라 차단하면서 파이프라인의 연속성을 유지합니다. 동결 기간이 정의되면 job 이 실패하고 파이프라인은 배포 없이 진행할 수 있습니다. 동결 기간이 끝난 뒤에는 수동 배포가 가능합니다.

이 방식은 중요한 유지 관리 기간에 배포를 통제하고 CI/CD 파이프라인이 끊기지 않고 흐르도록 보장합니다.

UI에서 배포 동결 기간을 설정하려면 다음 단계를 수행합니다.

1. Maintainer 권한이 있는 사용자로 GitLab에 로그인합니다.
2. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
3. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
4. Deploy freezes로 스크롤합니다.
5. Expand를 선택해 배포 동결 표를 확인합니다.
6. Add deploy freeze를 선택해 배포 동결 모달을 엽니다.
7. 설정하려는 배포 동결 기간의 시작 시간, 종료 시간, 시간대를 입력합니다.
8. 모달에서 Add deploy freeze를 선택합니다.
9. 배포 동결을 저장한 뒤에는 편집 버튼 (✏️)을 선택해 편집하고, 삭제 버튼 ([remove])을 선택해 제거할 수 있습니다.

프로젝트에 동결 기간이 여러 개 있으면 모든 기간이 적용됩니다. 기간이 겹치면 동결은 겹치는 전체 기간을 포함합니다.

자세한 내용은 배포 안전성을 참고합니다.

릴리스 권한#

릴리스 보기 및 에셋 다운로드#

• Reporter, Developer, Maintainer 또는 Owner 권한이 있는 사용자는 프로젝트 릴리스에 대한 읽기 및 다운로드 액세스 권한을 가집니다.
• Guest 권한이 있는 사용자도 프로젝트 릴리스에 대한 읽기 및 다운로드 액세스 권한을 가집니다. 여기에는 연결된 Git 태그 이름, 릴리스 설명, 릴리스 작성자 정보가 포함됩니다. 다만 소스 코드나 릴리스 증거 같은 다른 리포지터리 관련 정보는 가려집니다.

소스 코드 액세스를 허용하지 않고 릴리스 게시#

소스 코드나 릴리스 증거 같은 리포지터리 관련 정보는 프로젝트 멤버에게만 공개한 상태로, 릴리스는 프로젝트 멤버가 아닌 사람도 액세스할 수 있게 만들 수 있습니다. 이 설정은 릴리스로 새 소프트웨어 버전에 대한 액세스를 제공하되 소스 코드는 공개하지 않으려는 프로젝트에 적합합니다.

릴리스를 공개적으로 제공하려면 다음 프로젝트 설정을 지정합니다.

• Project visibility를 Public으로 설정
• Repository를 활성화하고 Only Project Members로 설정
• Releases를 활성화하고 Everyone With Access로 설정

릴리스와 에셋 생성, 업데이트, 삭제#

• Developer, Maintainer 또는 Owner 권한이 있는 사용자는 프로젝트 릴리스와 에셋에 대한 쓰기 액세스 권한을 가집니다.
• 릴리스가 보호된 태그에 연결되어 있으면 해당 사용자에게 보호된 태그를 생성할 권한도 있어야 합니다.

릴리스 권한을 제어하는 예로, 태그를 와일드카드(*)로 보호하고 Allowed to create 칼럼에 Maintainer를 설정하면 Maintainer 또는 Owner 권한이 있는 사용자만 릴리스를 생성, 업데이트, 삭제할 수 있게 할 수 있습니다.

릴리스 메트릭#

히스토리

• GitLab Premium 13.9에서 도입되었습니다.

그룹 수준의 릴리스 메트릭은 Group > Analytics > CI/CD로 이동해 확인할 수 있습니다. 이 메트릭에는 다음이 포함됩니다.

• 그룹 내 릴리스 총 개수
• 그룹 내 프로젝트 중 릴리스가 하나 이상 있는 프로젝트의 비율

동작하는 예제 프로젝트#

Guided Exploration 프로젝트 Utterly Automated Software and Artifact Versioning with GitVersion은 다음을 보여 줍니다.

• GitLab 릴리스 사용.
• GitLab CLI 사용.
• Generic 패키지 생성.
• 패키지를 릴리스에 연결.
• GitVersion이라는 도구로 복잡한 리포지터리의 버전을 자동으로 판별하고 증가시키기.

이 예제 프로젝트는 테스트용으로 자신의 그룹이나 인스턴스에 복사할 수 있습니다. 어떤 GitLab CI 패턴을 추가로 보여 주는지는 프로젝트 페이지에서 자세히 확인할 수 있습니다.

문제 해결#

릴리스와 에셋을 생성, 업데이트, 삭제할 때 발생하는 오류#

릴리스가 보호된 태그에 연결되어 있으면 UI/API 요청에서 다음과 같은 인가 실패가 발생할 수 있습니다.

• 403 Forbidden
• Something went wrong while creating a new release

해당 사용자 또는 서비스/봇 계정에 보호된 태그를 생성할 권한도 있는지 확인합니다.

자세한 내용은 릴리스 권한을 참고합니다.

스토리지에 관한 참고 사항#

이 기능은 Git 태그를 기반으로 구축되어 있어, 릴리스 자체를 생성하는 데 필요한 것 외에는 사실상 추가 데이터가 필요하지 않습니다. 추가 에셋과 자동으로 생성되는 릴리스 증거는 스토리지를 소비합니다.

GitLab CLI 버전 요구 사항#

release 키워드의 사용 방식이 변경될 예정입니다. release-cli 도구는 GitLab CLI 도구로 대체되고 있습니다.

GitLab CLI 도구 v1.58.0 이상을 사용해야 하며, 그렇지 않으면 다음 오류 메시지나 경고 중 하나를 받을 수 있습니다.

• Error: glab command not found. Please install glab v1.58.0 or higher.
• Error: Please use glab v1.58.0 or higher.
• Warning: release-cli will not be supported after 20.0. Please use glab version >= 1.58.0.

GitLab CLI 도구를 갖추는 방법은 두 가지입니다.

• registry.gitlab.com/gitlab-org/release-cli:<version> 컨테이너 이미지를 사용하는 경우에는 registry.gitlab.com/gitlab-org/cli:v1.58.0 또는 glab v1.58.0 이 포함된 registry.gitlab.com/gitlab-org/release-cli:v0.24.0 중 하나를 사용할 수 있습니다.
• 러너에 release-cli 또는 GitLab CLI 도구를 직접 설치한 경우에는 GitLab CLI 버전이 v1.58.0 이상인지 확인합니다.