• GitLab Pages 요구 사항
• GitLab.com의 GitLab Pages
• 예제 프로젝트
• 사용자 정의 오류 코드 페이지
• GitLab Pages에서 리다이렉트
• 페이지 제거하기
• 서브도메인의 하위 도메인
• 프로젝트 및 그룹의 GitLab Pages
• Pages의 특정 구성 옵션
  • 일반 HTML 웹사이트용 .gitlab-ci.yml
  • 정적 사이트 생성기용 .gitlab-ci.yml
  • 코드가 포함된 리포지터리용 .gitlab-ci.yml
  • 압축된 에셋 제공
• 프로젝트 및 그룹의 GitLab Pages
• Pages의 특정 구성 옵션
  • 일반 HTML 웹사이트용 .gitlab-ci.yml
  • 정적 사이트 생성기용 .gitlab-ci.yml
  • 코드가 포함된 리포지터리용 .gitlab-ci.yml
  • 압축된 에셋 제공
  • 모호한 URL 해결
• 기본 폴더 사용자 정의
• 알려진 문제
• 문제 해결
  • GitLab Pages 사이트 URL에 액세스할 때 404 오류
  • 깨진 상대적 링크
  • Safari에서 미디어 콘텐츠를 재생할 수 없는 경우

GitLab Pages 설정

이 문서는 GitLab Pages가 제공하는 옵션과 설정을 탐색하기 위한 사용자 가이드입니다.

먼저 GitLab Pages에 대해 익숙해지려면 다음을 참고하세요:

• GitLab Pages 소개를 읽어보세요.
• Pages 시작하기를 배우세요.
• 귀하의 GitLab 인스턴스 전반에 GitLab Pages를 활성화하는 방법은 관리자 문서를 참조하세요.

GitLab Pages 요구 사항

간단히 말해서, GitLab Pages에 웹사이트를 업로드하려면 다음이 필요합니다:

1. 인스턴스의 도메인: GitLab Pages에 사용되는 도메인 이름 (관리자에게 문의하세요).
2. GitLab CI/CD: 귀하의 리포지터리의 루트 디렉터리에 특정 작업인 pages가 포함된 .gitlab-ci.yml 파일.
3. 프로젝트용 GitLab Runner가 활성화되어 있어야 합니다.

GitLab.com의 GitLab Pages

웹사이트를 호스팅하기 위해 GitLab.com의 GitLab Pages를 사용하는 경우:

• GitLab.com의 GitLab Pages용 도메인 이름은 gitlab.io입니다.
• 사용자 정의 도메인 및 TLS 지원이 활성화되어 있습니다.
• 기본적으로 인스턴스 러너가 활성화되어 무료로 제공되며 웹사이트 빌드에 사용할 수 있습니다. 원하는 경우 사용자 고유의 러너를 사용할 수도 있습니다.

예제 프로젝트

예제 프로젝트의 완전한 디렉터리은 GitLab Pages 그룹에서 확인할 수 있습니다. 기여는 언제나 환영합니다.

사용자 정의 오류 코드 페이지

public/ 디렉터리의 루트에 403.html 및 404.html 파일을 생성하여 고유의 403 및 404 오류 페이지를 제공할 수 있습니다. 보통 이것은 귀하의 프로젝트의 루트 디렉터리일 수 있지만, 정적 생성기 구성에 따라 다를 수 있습니다.

404.html의 경우 다양한 시나리오가 있습니다. 예를 들어:

• 프로젝트 Pages( /project-slug/ 아래에서 제공)를 사용하여 /project-slug/non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 먼저 /project-slug/404.html, 그리고 /404.html를 제공하려고 합니다.
• 사용자 또는 그룹 Pages(/에서 제공)를 사용하여 /non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 /404.html만 제공하려고 합니다.
• 사용자 정의 도메인을 사용하여 /non/existing_file에 액세스하려고 하는 경우, GitLab Pages는 /404.html만 제공하려고 합니다.

GitLab Pages에서 리다이렉트

_redirects 파일을 사용하여 사이트의 리다이렉트를 구성할 수 있습니다. 자세한 정보는 GitLab Pages를 위한 리다이렉트 생성을 참조하세요.

페이지 제거하기

귀하의 페이지를 제거하려면:

1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 귀하의 프로젝트를 찾습니다.
2. 배포 > 페이지를 선택합니다.
3. 페이지 제거를 선택합니다.

서브도메인의 하위 도메인

GitLab 인스턴스의 최상위 도메인(*.example.io) 아래에서 Pages를 사용하는 경우, 하위 도메인의 HTTPS를 사용할 수 없습니다. 만약 귀하의 네임스페이스나 그룹 이름에 점이 포함된 경우(예: foo.bar), https://foo.bar.example.io는 작동하지 않습니다.

이 제한은 TLS 프로토콜 때문에 발생합니다. HTTP 페이지는 HTTPS로 리디렉트하지 않는 한 작동합니다.

프로젝트 및 그룹의 GitLab Pages

GitLab Pages 웹사이트를 프로젝트에 호스팅해야 합니다. 이 프로젝트는 비공개, 내부, 또는 공개일 수 있으며 그룹 또는 하위 그룹에 속해 있을 수 있습니다.

그룹 웹사이트의 경우, 그룹은 최상위에 있어야 하며 하위 그룹이 아니어야 합니다.

프로젝트 웹사이트의 경우, 먼저 프로젝트를 생성하고 http(s)://namespace.example.io/project-path에서 액세스할 수 있습니다.

Pages의 특정 구성 옵션

특정 사용 사례에 대해 GitLab CI/CD를 설정하는 방법을 배우세요.

일반 HTML 웹사이트용 .gitlab-ci.yml

리포지터리에 다음과 같은 파일이 포함되어 있는 것으로 가정합니다:

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

그런 다음 아래의 .gitlab-ci.yml 예제는 프로젝트의 루트 디렉터리의 모든 파일을 public/ 디렉터리로 이동시킵니다. .public 이름을 사용하는 것은 cp가 자기 자신을 무한 루프에 복사하지 않도록하기 위한 것입니다:

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

정적 사이트 생성기용 .gitlab-ci.yml

단계별 가이드를 참조하세요.

코드가 포함된 리포지터리용 .gitlab-ci.yml

GitLab Pages는 기본적으로 브랜치/태그에 구애받지 않으며 배포는 오직 귀하가 .gitlab-ci.yml에서 지정한 내용에만 의존합니다. 당신이 pages 작업을 제한할 수 있도록 함으로써 그것을 사용할 수 있습니다. rules:if을 사용하여 pages 전용 브랜치에 새 커밋을 푸시할 때마다.

이렇게 하면 프로젝트의 코드를 main 브랜치에 두고 정적 생성기 사이트를 호스팅하기 위해 고립된 브랜치(여기서 pages라고 합니다)를 사용할 수 있습니다.

다음과 같이 새로운 빈 브랜치를 만들 수 있습니다:

git checkout --orphan pages

새로운 이 브랜치에서의 첫 번째 커밋은 부모가 없으며 모든 다른 브랜치와 커밋과 완전히 연결되지 않은 새로운 히스토리의 루트입니다. 귀하의 정적 생성기의 소스 파일을 pages 브랜치에 푸시하세요.

가장 중요한 줄은 마지막 줄로, 모든 것을 pages 브랜치에서 실행하도록 지정하는 것입니다:

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

main 브랜치에 다른 파일이 있는 예제와 Jekyll의 소스 파일이 포함된 pages 브랜치를 참조하세요. 또한, 이것은 .gitlab-ci.yml도 포함합니다.

압축된 에셋 제공

대부분의 최신 브라우저는 압축된 형식으로 파일을 다운로드할 수 있습니다. 이는 파일의 크기를 줄이는 것으로써 다운로드 속도를 높이게 됩니다.

압축 파일을 제공하기 전에 Pages는 동일한 파일이 .br 또는 .gz 확장자로 있는지 확인합니다. 브라우저가 압축 파일을 받을 수 있는 경우, Pages는 압축 해제된 버전 대신 압축 파일을 제공합니다.

이 기능을 활용하려면 업로드한 artifact는 다음 구조여야 합니다:

public/
├─┬ index.html
│ | index.html.br
│ └ index.html.gz
│
├── css/
│   └─┬ main.css
│     | main.css.br
│     └ main.css.gz
│
└── js/
    └─┬ main.js
      | main.js.br
      └ main.js.gz

이것은 .gitlab-ci.yml pages 작업에서 다음과 같은 script: 명령을 포함하여 달성할 수 있습니다:

pages:
  # 다른 지시
  script:
    # 먼저 public/ 디렉터리를 빌드하세요
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec brotli -f -k {} \;

파일을 사전 압축하고 artifact에 두 가지 버전을 포함시킴으로써, Pages는 압축된 내용과 압축 해제된 내용을 모두 요청에 제공함으로써 파일의 압축된 및 압축 해제된 콘텐츠를 요청할 수 있습니다.

제약 사항:

• 웹브라우저가 HTTPS로 리디렉트되지 않는 한 https://foo.bar.example.io는 작동하지 않습니다.

프로젝트 및 그룹의 GitLab Pages

GitLab Pages 웹사이트를 프로젝트에 호스팅해야 합니다. 이 프로젝트는 비공개, 내부, 또는 공개일 수 있으며 그룹 또는 하위 그룹에 속해 있을 수 있습니다.

그룹 웹사이트의 경우, 그룹은 최상위에 있어야 하며 하위 그룹이 아니어야 합니다.

프로젝트 웹사이트의 경우, 먼저 프로젝트를 생성하고 http(s)://namespace.example.io/project-path에서 액세스할 수 있습니다.

Pages의 특정 구성 옵션

특정 사용 사례에 대해 GitLab CI/CD를 설정하는 방법을 배우세요.

일반 HTML 웹사이트용 .gitlab-ci.yml

리포지터리에 다음과 같은 파일이 포함되어 있는 것으로 가정합니다:

├── index.html
├── css
│   └── main.css
└── js
    └── main.js

그런 다음 아래의 .gitlab-ci.yml 예제는 프로젝트의 루트 디렉터리의 모든 파일을 public/ 디렉터리로 이동시킵니다. .public 이름을 사용하는 것은 cp가 자기 자신을 무한 루프에 복사하지 않도록하기 위한 것입니다:

pages:
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

정적 사이트 생성기용 .gitlab-ci.yml

단계별 가이드를 참조하세요.

코드가 포함된 리포지터리용 .gitlab-ci.yml

GitLab Pages는 기본적으로 브랜치/태그에 구애받지 않으며 배포는 오직 귀하가 .gitlab-ci.yml에서 지정한 내용에만 의존합니다. 당신이 pages 작업을 제한할 수 있음으로써 그것을 사용할 수 있습니다. rules:if을 사용하여 pages 전용 브랜치에 새 커밋을 푸시할 때마다.

이렇게 하면 프로젝트의 코드를 main 브랜치에 두고 정적 생성기 사이트를 호스팅하기 위해 고립된 브랜치(여기서 pages라고 합니다)를 사용할 수 있습니다.

다음과 같이 새로운 빈 브랜치를 만들 수 있습니다:

git checkout --orphan pages

새로운 이 브랜치에서의 첫 번째 커밋은 부모가 없으며 모든 다른 브랜치와 커밋과 완전히 연결되지 않은 새로운 히스토리의 루트입니다. 귀하의 정적 생성기의 소스 파일을 pages 브랜치에 푸시하세요.

가장 중요한 줄은 마지막 줄로, 모든 것을 pages 브랜치에서 실행하도록 지정하는 것입니다:

image: ruby:2.6

pages:
  script:
    - gem install jekyll
    - jekyll build -d public/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_REF_NAME == "pages"'

main 브랜치에 다른 파일이 있는 예제와 Jekyll의 소스 파일이 포함된 pages 브랜치를 참조하세요. 또한, 이것은 .gitlab-ci.yml도 포함합니다.

압축된 에셋 제공

대부분의 최신 브라우저

모호한 URL 해결

GitLab Pages는 확장자를 포함하지 않은 URL에 대한 요청을 받을 때 어떤 파일을 제공할지에 대한 가정을 합니다.

다음 파일들로 배포된 페이지 사이트를 고려해보세요.

public/
├── index.html
├── data.html
├── info.html
├── data/
│   └── index.html
└── info/
    └── details.html

특히 URL이 디렉터리만 지정하는 경우 항상 index.html 파일을 찾습니다. URL이 존재하지 않는 파일을 참조하지만 URL에 .html을 추가하면 존재하는 파일이 있는 경우 해당 파일이 제공됩니다. 위의 페이지 사이트를 사용한 몇 가지 예시를 살펴보겠습니다.

public/data/index.html이 존재하는 경우 /data 및 /data/ URL 경로에 대해 public/data.html 파일보다 우선합니다.

기본 폴더 사용자 정의

• GitLab 16.1에서 FF_CONFIGURABLE_ROOT_DIR라는 Pages 플래그로 도입. 기본 설정은 비활성화되어 있습니다.
• GitLab 16.1에서 GitLab.com에 활성화.
• GitLab 16.2에서 Self-Managed에 활성화.

기본적으로 사이트의 정적 파일을 포함하는 artifact 폴더의 이름은 public이어야 합니다.

해당 폴더 이름을 다른 값으로 변경하려면 .gitlab-ci.yml의 pages 작업 구성에 publish 속성을 추가하세요.

다음 예제는 dist라는 폴더를 대신하여 배포하는 예제입니다.

pages:
  script:
    - npm run build
  artifacts:
    paths:
      - dist
  publish: dist

public 외의 폴더 이름을 사용하는 경우에는 artifact로서와 publish 속성 아래로 배포할 디렉터리를 명시해야 합니다. 이 둘 다 필요한 이유는 여러 경로를 artifact로 정의할 수 있으며, GitLab은 어떤 것을 배포할 지 모릅니다.

알려진 문제

알려진 문제의 디렉터리은 GitLab public issue tracker를 참조하세요.

문제 해결

GitLab Pages 사이트 URL에 액세스할 때 404 오류

이 문제는 공개 디렉터리에 index.html 파일이 없는 경우에 발생할 수 있습니다. Pages 사이트를 배포한 후 404 오류가 발생하는 경우, 공개 디렉터리에 index.html 파일이 있는지 확인하세요. test.html과 같이 다른 이름의 파일이 있는 경우에도 Pages 사이트에는 접근할 수 있지만 전체 경로가 필요합니다. 예: https//group-name.pages.example.com/project-slug/test.html.

최신 파이프라인의 artifact를 조회해서 공개 디렉터리의 내용을 확인할 수 있습니다.

프로젝트의 Pages URL로 공개 디렉터리에 나열된 파일에 액세스할 수 있습니다.

404는 잘못된 권한과 관련될 수도 있습니다. Pages Access Control이 활성화되어 있고 사용자가 Pages URL로 이동하여 404 응답을 받는 경우 사용자가 사이트를 볼 수 있는 권한이 없을 수 있습니다. 이 문제를 해결하려면 사용자가 프로젝트의 구성원인지 확인하세요.

깨진 상대적 링크

GitLab Pages는 확장자 없는 URL을 지원합니다. 그러나 이슈 #354에서 설명한 문제로 인해 확장자 없는 URL이 슬래시(/)로 끝나면 페이지의 상대적 링크가 깨집니다.

이 문제를 해결하려면:

• 페이지로 향하는 URL에 확장자가 있는지 확인하거나 슬래시를 포함하지 않도록 하세요.
• 가능하다면 사이트에서는 절대 URL만 사용하세요.

Safari에서 미디어 콘텐츠를 재생할 수 없는 경우

Safari는 미디어 콘텐츠를 재생하려면 웹 서버가 Range 요청 헤더를 지원해야 합니다. GitLab Pages가 HTTP Range 요청을 제공하려면 .gitlab-ci.yml 파일에서 다음 두 변수를 사용해야 합니다.

pages:
  stage: deploy
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - echo "Deploying pages"
  artifacts:
    paths:
      - public
  environment: production

FF_USE_FASTZIP 변수는 ARTIFACT_COMPRESSION_LEVEL에 필요한 피처 플래그를 활성화합니다.