병렬 배포를 사용하면 GitLab Pages 사이트의 여러 버전을 동시에 게시할 수 있습니다. 각 버전은 지정한 경로 접두사를 기준으로 고유한 URL을 가집니다.

병렬 배포는 다음 용도로 사용합니다.

• 프로덕션에 병합하기 전에 개발 브랜치의 변경 사항을 테스트하는 워크플로를 개선합니다.
• 이해관계자와 작업 중인 미리 보기를 공유해 피드백을 받습니다.
• 여러 소프트웨어 버전의 문서를 동시에 유지합니다.
• 대상 독자별로 현지화된 콘텐츠를 게시합니다.
• 최종 게시 전에 검토할 스테이징 환경을 만듭니다.

사이트의 각 버전은 지정한 경로 접두사를 기준으로 고유한 URL을 가집니다. 병렬 배포가 유지되는 기간은 직접 제어합니다. 기본적으로 24시간 후에 만료되지만, 검토 일정에 맞게 이 기간을 조정할 수 있습니다.

병렬 배포 만들기#

사전 요건:

• 최상위 네임스페이스에 사용 가능한 병렬 배포 슬롯이 있어야 합니다.

병렬 배포를 만들려면 다음 단계를 따릅니다.

1. .gitlab-ci.yml 파일에 path_prefix를 지정한 Pages job을 추가합니다.

   pages:
     stage: deploy
     script:
       - echo "Pages accessible through ${CI_PAGES_URL}"
     pages:  # specifies that this is a Pages job and publishes the default public directory
       path_prefix: "$CI_COMMIT_BRANCH"
   

   path_prefix 값은 다음 규칙을 따릅니다.

   • 소문자로 변환됩니다.
   • 숫자(0-9), 문자(a-z), 마침표(.)를 포함할 수 있습니다.
   • 그 밖의 문자는 하이픈(-)으로 대체됩니다.
   • 하이픈(-)이나 마침표(.)로 시작하거나 끝날 수 없으며, 해당 문자는 제거됩니다.
   • 63바이트 이하여야 합니다. 이를 초과하는 부분은 잘립니다.

2. 선택 사항. 동적 접두사를 사용하려면 path_prefix에 CI/CD 변수를 사용합니다. 예를 들면 다음과 같습니다.

   pages:
     path_prefix: "mr-$CI_MERGE_REQUEST_IID" # Results in paths like mr-123
   

3. 선택 사항. 배포의 만료 시간을 설정하려면 expire_in을 추가합니다.

   pages:
     pages:
       path_prefix: "$CI_COMMIT_BRANCH"
       expire_in: 1 week
   

   기본적으로 병렬 배포는 24시간 후에 만료됩니다.

4. 변경 사항을 커밋하고 리포지터리에 푸시합니다.

배포는 다음 주소에서 접근할 수 있습니다.

• 고유 도메인을 사용하는 경우: https://project-123456.gitlab.io/your-prefix-name.
• 고유 도메인을 사용하지 않는 경우: https://namespace.gitlab.io/project/your-prefix-name.

사이트 도메인과 public 디렉터리 사이의 URL 경로는 path_prefix로 결정됩니다. 예를 들어 기본 배포의 콘텐츠가 /index.html에 있다면, 접두사가 staging 인 병렬 배포에서는 같은 콘텐츠를 /staging/index.html에서 볼 수 있습니다.

경로 충돌을 방지하려면 사이트에 이미 있는 폴더 이름과 같은 경로 접두사는 사용하지 않습니다. 자세한 내용은 경로 충돌을 참고합니다.

예시 구성#

https://gitlab.example.com/namespace/project와 같은 프로젝트를 예로 듭니다. 기본적으로 이 프로젝트의 기본 Pages 배포는 다음 주소로 접근합니다.

• 고유 도메인을 사용하는 경우: https://project-123456.gitlab.io/.
• 고유 도메인을 사용하지 않는 경우: https://namespace.gitlab.io/project.

pages.path_prefix가 path_prefix = $CI_COMMIT_BRANCH처럼 프로젝트 브랜치 이름으로 구성되어 있고 username/testing_feature라는 브랜치가 있다면, 이 병렬 Pages 배포는 다음 주소로 접근합니다.

• 고유 도메인을 사용하는 경우: https://project-123456.gitlab.io/username-testing-feature.
• 고유 도메인을 사용하지 않는 경우: https://namespace.gitlab.io/project/username-testing-feature.

한도#

병렬 배포 수는 최상위 네임스페이스 단위로 제한됩니다. 구체적인 한도는 다음을 참고합니다.

• GitLab.com은 기타 한도를 참고합니다.
• GitLab Self-Managed는 병렬 Pages 배포 수를 참고합니다.

네임스페이스의 활성 배포 수를 즉시 줄이려면 일부 배포를 삭제합니다. 자세한 내용은 배포 삭제를 참고합니다.

만료 시간을 구성해 오래된 배포를 자동으로 삭제하려면 배포 만료를 참고합니다.

만료#

기본적으로 병렬 배포는 24시간 후에 만료되며, 그 후 삭제됩니다. 자체 호스팅 인스턴스를 사용하는 경우 인스턴스 관리자가 다른 기본 기간을 구성할 수 있습니다.

만료 시간을 조정하려면 pages.expire_in을 구성합니다.

배포가 자동으로 만료되지 않게 하려면 pages.expire_in을 never로 설정합니다.

경로 충돌#

pages.path_prefix는 CI/CD 변수에서 동적 값을 받을 수 있으며, 그 결과 사이트의 기존 경로와 충돌하는 Pages 배포가 생길 수 있습니다. 예를 들어 다음 경로를 가진 기존 GitLab Pages 사이트가 있다고 가정합니다.

/index.html
/documents/index.html

pages.path_prefix가 documents 이면 해당 버전이 기존 경로를 덮어씁니다. 즉, https://namespace.gitlab.io/project/documents/index.html은 사이트 main 배포의 documents/index.html 이 아니라 사이트 documents 배포의 /index.html을 가리킵니다.

CI/CD 변수를 다른 문자열과 조합하면 경로 충돌 가능성을 줄일 수 있습니다. 예를 들면 다음과 같습니다.

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # No prefix by default (main)
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$PAGES_PREFIX"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run on default branch (with default PAGES_PREFIX)
    - if: $CI_COMMIT_BRANCH == "staging" # Run on main (with default PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # Prefix with _stg for the staging branch
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # Conditionally change the prefix for Merge Requests
      when: manual # Run pages manually on Merge Requests
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # Prefix with the mr-<iid>, like `mr-123`

동적 접두사를 위해 변수와 문자열을 조합하는 다른 예시는 다음과 같습니다.

• pages.path_prefix: 'mr-$CI_COMMIT_REF_SLUG': mr-branch-name처럼 브랜치 또는 태그 이름 앞에 mr-를 붙입니다.
• pages.path_prefix: '_${CI_MERGE_REQUEST_IID}_': _123_처럼 머지 리퀘스트 번호의 앞뒤에 _를 붙입니다.

앞의 YAML 예시는 사용자 정의 job 이름을 사용합니다.

병렬 배포를 사용하여 Pages 환경 만들기#

병렬 GitLab Pages 배포를 사용해 새 환경을 만들 수 있습니다. 예를 들면 다음과 같습니다.

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  variables:
    PAGES_PREFIX: "" # no prefix by default (run on the default branch)
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$PAGES_PREFIX"
  environment:
    name: "Pages ${PAGES_PREFIX}"
    url: $CI_PAGES_URL
  rules:
    - if: $CI_COMMIT_BRANCH == "staging" # ensure to run on the default branch (with default PAGES_PREFIX)
      variables:
        PAGES_PREFIX: '_stg' # prefix with _stg for the staging branch
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" # conditionally change the prefix on Merge Requests
      when: manual # run pages manually on Merge Requests
      variables:
        PAGES_PREFIX: 'mr-$CI_MERGE_REQUEST_IID' # prefix with the mr-<iid>, like `mr-123`

이 구성을 사용하면 사용자는 UI에서 각 GitLab Pages 배포에 접근할 수 있습니다. Pages에 환경을 사용하면 모든 Pages 환경이 프로젝트 환경 목록에 표시됩니다.

유사한 환경을 그룹으로 묶을 수도 있습니다.

앞의 YAML 예시는 사용자 정의 job 이름을 사용합니다.

자동 정리#

path_prefix가 지정된 머지 리퀘스트로 생성된 병렬 Pages 배포는 해당 머지 리퀘스트가 닫히거나 병합될 때 자동으로 삭제됩니다.

리디렉션과 함께 사용#

리디렉션은 절대 경로를 사용합니다. 병렬 배포는 하위 경로에서 제공되므로, 병렬 배포에서 리디렉션이 동작하려면 _redirects 파일을 추가로 수정해야 합니다.

기존 파일이 항상 리디렉션 규칙보다 우선하므로, 접두사가 붙은 경로에 대한 요청을 받으려면 스플랫 자리 표시자를 사용할 수 있습니다.

path_prefix가 /mr-${$CI_MERGE_REQUEST_IID} 인 경우, 기본 배포와 병렬 배포 양쪽의 요청을 리디렉션하려면 다음 _redirect 파일 예시를 참고해 수정합니다.

# Redirect the primary deployment
/will-redirect.html /redirected.html 302

# Redirect parallel deployments
/*/will-redirect.html /:splat/redirected.html 302