- GitLab Pages 요구 사항
- GitLab.com의 GitLab Pages
- 예제 프로젝트
- 사용자 정의 오류 코드 페이지
- GitLab Pages의 리디렉션
- 페이지 제거
- 하위 도메인의 하위 도메인
- 프로젝트 및 그룹의 GitLab Pages
- 고유 도메인 활성화
- Pages에 대한 특정 구성 옵션
- 기본 폴더 사용자 정의
- 알려진 문제
- 문제 해결
GitLab Pages 설정
이 문서는 GitLab Pages에서 제공하는 옵션과 설정을 탐색하기 위한 사용자 가이드입니다.
먼저 GitLab Pages에 익숙해지려면:
- GitLab Pages 소개를 읽어보세요.
- Pages 시작하기를 배워보세요.
- 귀하의 GitLab 인스턴스 전반에 걸쳐 GitLab Pages를 활성화하는 방법을 관리자 설명서에서 알아보세요.
GitLab Pages 요구 사항
간단히 말해, GitLab Pages에 웹사이트를 업로드하려면 다음이 필요합니다:
- 인스턴스의 도메인: GitLab Pages에 사용되는 도메인 이름 (관리자에게 문의하세요).
- GitLab CI/CD: 귀하의 저장소의 루트 디렉토리에 특정 작업이름이
pages
인.gitlab-ci.yml
파일. - 프로젝트용 GitLab Runner가 활성화되어 있어야 합니다.
GitLab.com의 GitLab Pages
만약 귀하가 귀하의 웹사이트를 호스팅하기 위해 GitLab.com의 GitLab Pages을 사용 중이라면:
- GitLab.com의 GitLab Pages의 도메인 이름은 ‘gitlab.io’입니다.
- 사용자 정의 도메인 및 TLS 지원이 활성화되어 있습니다.
- 인스턴스 러너가 기본적으로 활성화되어 있으며 무료로 제공되며 웹사이트를 빌드하는 데 사용할 수 있습니다. 원하는 경우 직접 러너를 사용할 수도 있습니다.
예제 프로젝트
예제 프로젝트의 완전한 목록은 GitLab Pages 그룹을 방문하시기 바랍니다. 기여는 언제나 환영합니다.
사용자 정의 오류 코드 페이지
403.html
및 404.html
파일을 public/
디렉토리의 루트에 생성하여 고유한 403
및 404
오류 페이지를 제공할 수 있습니다.
일반적으로 이는 귀하의 프로젝트의 루트 디렉토리이지만, 정적 생성기 설정에 따라 다를 수 있습니다.
404.html
의 경우, 다양한 시나리오가 있습니다. 예를 들어:
- 프로젝트 페이지(
/project-slug/
하위에서 제공)를 사용하고/project-slug/non/existing_file
에 액세스하려고 하는 경우, GitLab Pages는 먼저/project-slug/404.html
, 그 후/404.html
를 제공하려고 합니다. - 사용자 또는 그룹 페이지(
/
하위에서 제공)를 사용하고/non/existing_file
에 액세스하려고 하는 경우, GitLab Pages는/404.html
를 제공하려고 합니다. - 사용자 정의 도메인을 사용하고
/non/existing_file
에 액세스하려고 하는 경우, GitLab Pages는/404.html
만 제공하려고 합니다.
GitLab Pages의 리디렉션
_redirects
파일을 사용하여 사이트의 리디렉션을 구성할 수 있습니다. 자세한 내용은
GitLab Pages를 위한 리디렉션 생성을 참조하십시오.
페이지 제거
페이지를 제거하려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
- 배포 > Pages를 선택하세요.
- 페이지 제거를 선택하세요.
하위 도메인의 하위 도메인
GitLab 인스턴스의 최상위 도메인 (*.example.io
) 하위에서 Pages를 사용하는 경우, 하위 도메인에 HTTPS를 사용할 수 없습니다.
귀하의 네임스페이스 또는 그룹 이름에 점이 포함된 경우(foo.bar
와 같은), 도메인 https://foo.bar.example.io
는 작동하지 않습니다.
이 제한은 TLS 프로토콜 때문에 발생합니다. HTTP 페이지는 HTTP를 HTTPS로 리디렉트하지 않는 한 작동합니다.
프로젝트 및 그룹의 GitLab Pages
귀하는 GitLab Pages 웹사이트를 프로젝트에 호스팅해야 합니다. 이 프로젝트는 비공개, 내부, 또는 공개이며 그룹 또는 하위그룹에 속할 수 있습니다.
그룹 웹사이트의 경우, 그룹은 최상위에 있어야 하며 하위그룹이 아니어야 합니다.
프로젝트 웹사이트의 경우, 먼저 프로젝트를 만들고 http(s)://namespace.example.io/project-path
에서 액세스할 수 있습니다.
고유 도메인 활성화
- GitLab 15.9에서 플래그인
pages_unique_domain
이 함께 소개되었습니다. 기본적으로 비활성화되어 있습니다.- GitLab 15.11에서 기본적으로 활성화되었습니다.
- GitLab 16.3에서 기능 플래그가 제거되었습니다.
기본적으로 그룹 내 모든 프로젝트가 동일한 도메인, 예를 들어 group.gitlab.io
를 공유합니다. 이는 모든 프로젝트에 대해 쿠키도 공유된다는 의미입니다.
프로젝트가 고유 Pages 도메인을 사용하도록 보장하려면 다음과 같은 기능을 활성화하세요:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
- 배포 > Pages를 선택하세요.
- 고유 도메인 사용 확인란을 선택하세요.
- 변경 사항 저장을 선택하세요.
Pages에 대한 특정 구성 옵션
특정 사용 사례에 대해 GitLab CI/CD를 설정하는 방법을 알아보세요.
.gitlab-ci.yml
: 일반 HTML 웹사이트용
저장소에 다음 파일이 포함되어 있는 경우:
├── index.html
├── css
│ └── main.css
└── js
└── main.js
아래의 .gitlab-ci.yml
예제는 프로젝트의 루트 디렉토리의 모든 파일을 public/
디렉토리로 이동합니다. .public
부적합은 cp
가 public/
을 무한 루프로 복사하는 것을 방지합니다:
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
작업을 제한할 수 있습니다.
이렇게 하면 프로젝트 코드가 main
브랜치에 있고 고립된 브랜치(이름을 pages
로 지정)를 사용하여 정적 생성기 사이트를 호스팅할 수 있습니다.
다음과 같이 새 빈 브랜치를 생성할 수 있습니다:
git checkout --orphan pages
이 새로운 브랜치에서 생성된 첫 번째 커밋은 부모가 없으며 모든 다른 브랜치와 커밋과 완전히 분리된 새로운 히스토리의 루트입니다. 정적 생성기의 소스 파일을 pages
브랜치에 푸시하세요.
아래는 가장 중요한 줄이 마지막 줄로 지정되어 pages
브랜치에서 모든 것을 실행하도록 하는 .gitlab-ci.yml
의 복사본입니다:
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
브랜치를 보여줍니다.
압축된 에셋 제공
대부분의 현대 브라우저는 압축 형식으로 파일을 다운로드하는 것을 지원합니다. 이렇게 하면 파일 크기가 줄어들어 다운로드 속도가 빨라집니다.
압축되지 않은 파일을 제공하기 전에 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
작업에 다음과 같은 명령어를 포함하여야 합니다:
pages:
# Other directives
script:
# Build the public/ directory first
- 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는 파일을 요청할 때 압축 및 압축 해제된 콘텐츠를 모두 제공할 수 있습니다.
모호한 URL 해결
GitLab Pages는 확장자가 없는 URL을 받았을 때 서비스할 파일에 관한 가정을 합니다.
다음 파일이 포함된 Pages 사이트를 배포한다고 가정해 보겠습니다:
public/
├── index.html
├── data.html
├── info.html
├── data/
│ └── index.html
└── info/
└── details.html
Pages는 여러 다른 URL을 통해 이러한 파일에 도달할 수 있습니다. 특히, URL이 디렉토리만 지정된다면 항상 index.html
파일을 찾습니다. URL이 존재하지 않는 파일을 참조하더라도 URL에 .html
을 추가하면 존재하는 파일 대신 제공됩니다. 위의 Pages 사이트를 사용하여 다음과 같은 예제가 어떻게 작동하는지 살펴보세요:
URL 경로 | HTTP 응답 |
---|---|
/
|
200 OK : public/index.html
|
/index.html
|
200 OK : public/index.html
|
/index
|
200 OK : public/index.html
|
/data
|
302 Found : /data/ 로 재지정
|
/data/
|
200 OK : public/data/index.html
|
/data.html
|
200 OK : public/data.html
|
/info
|
302 Found : /info/ 로 재지정
|
/info/
|
404 Not Found 에러 페이지
|
/info.html
|
200 OK : public/info.html
|
/info/details
|
200 OK : public/info/details.html
|
/info/details.html
|
200 OK : public/info/details.html
|
기본 폴더 사용자 정의
- GitLab 16.1에 도입되었습니다. 기본으로 비활성화된
FF_CONFIGURABLE_ROOT_DIR
라는 페이지 플래그와 함께.- 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 공개 이슈 트래커를 참조하세요.
문제 해결
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이 슬래시( /
)로 끝나는 경우 페이지의 상대적 링크가 깨집니다.
이 문제를 해결하려면:
- Pages 사이트를 가리키는 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
에 필요한 기능 플래그를 활성화합니다.