pages 是用來存放純 html / js /css 網頁
gitlab 是一個控管 git 庫 (放程式檔案) 的地方
gitlab 與 pages 搭配起來就是當我開發程式或檔案，上傳到 gitlab 後，它會自動佈署到 pages，就可以直接透過網頁瀏覽內容
又或是你的專案是 npm 開發內容，它會自動轉成瀏覽器可讀的 js
首先
環境是 ↓
gitlab 連結 : git.ssorc.tw pages 連結: pages.ssorc.tw
gitlab 上的群組與專案:
<group>/<project> cross/testpages
如要 clone 它就長這樣子
git clone https://git.ssorc.tw/cross/testpages/
而 pages 連結可以是
<group>.pages.ssorc.tw/<project>
或
pages.ssorc.tw/<group>/<project>
↑ 要這方式就 gitlab 要多加這條設定 (不是再一個子網站的方式)
gitlab_pages['namespace_in_path'] = true
底下設定為↑ 方式
# 開始設定 gitlab.rb
external_url "https://git.ssorc.tw" nginx['enable'] = true nginx['redirect_http_to_https'] = true nginx['ssl_certificate'] = "/etc/gitlab/ssl/server.crt" nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/server.key" pages_external_url "https://pages.ssorc.tw" gitlab_pages['enable'] = true # 使用 pages.ssorc.tw 而不是 *.pages.ssorc.tw # false 的話就要使用 cross.pages.ssorc.tw/testpages gitlab_pages['namespace_in_path'] = true # 如會有 pages 會找不到 git.ssorc.tw，要加這個 gitlab_pages['internal_gitlab_server'] = "http://127.0.0.1:8080" # 如會有 ssl 驗證問題，加這個 gitlab_pages['internal_gitlab_server_cert'] = "/etc/gitlab/ssl/ca.crt" pages_nginx['enable'] = true pages_nginx['redirect_http_to_https'] = true pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/server.crt" pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/server.key"
讓 gitlab 設定套用起來
sudo gitlab-ctl reconfigure sudo gitlab-ctl restart
sudo /opt/gitlab/embedded/sbin/nginx -t -c /var/opt/gitlab/nginx/conf/nginx.conf
# pages 需要搭配 runner
Admin Area > CI/CD > Runners
Settings > CI/CD > Runners
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | bash apt update apt-get install gitlab-runner
# 或
# install gitlab runner # Download the binary for your system sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64 # Give it permission to execute sudo chmod +x /usr/local/bin/gitlab-runner # Create a GitLab Runner user sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash # Install and run as a service sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner sudo gitlab-runner start
# 純 html gitlab-runner register --url https://git.ssorc.tw --token glrt-xxxxxxxxxxxxxxxxxx.01.1801pgcp4 \ --executor shell \ --tls-ca-file /etc/gitlab/ssl/server.crt # 使用 docker / npm # tags global,pages,npm gitlab-runner register --url https://git.ssorc.tw --token glrt-xxxxxxxxxxxxxxxxxxxx.01.121u6vnn2 \ --executor docker \ --docker-image node:20 \ --description "global-pages-npm-runner" \ --tls-ca-file /etc/gitlab/ssl/server.crt sudo systemctl restart gitlab-runner
my-project/ ├─ public/ │ └─ index.html └─ .gitlab-ci.yml
<!doctype html> <html> <head> <meta charset="utf-8"> <title>GitLab Pages Test</title> </head> <body> <h1>Hello GitLab Pages</h1> </body> </html>
image: busybox pages: tags: - pages stage: deploy script: - echo "The site will be deployed to $CI_PAGES_URL" artifacts: paths: - public rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
↑ 編輯完後， git push 到 gitlab
就可在 gitlab 的 build > pipelines 重確認有沒有佈署成功
成功的話在 pages.ssorc.tw/cross/testpages 上可以看到佈署的網頁
Q
Running handlers:
[2026-05-17T19:08:01+08:00] ERROR: Running exception handlers
There was an error running gitlab-ctl reconfigure:
letsencrypt_certificate[git.ssorc.tw] (letsencrypt::http_authorization line 6) had an error: RuntimeError: acme_certificate[staging] (letsencrypt::http_authorization line 60) had an error: RuntimeError: ruby_block[create certificate for git.ssorc.tw] (letsencrypt::http_authorization line 112) had an error: RuntimeError: [git.ssorc.tw] Validation failed, unable to request certificate, Errors: [{url: https://acme-staging-v02.api.letsencrypt.org/acme/chall/293165773/1336776933/zmrQwg, status: invalid, error: {“type”=>”urn:ietf:params:acme:error:dns”, “detail”=>”DNS problem: NXDOMAIN looking up A for git.ssorc.tw – check that a DNS record exists for this domain; DNS problem: NXDOMAIN looking up AAAA for git.ssorc.tw – check that a DNS record exists for this domain”, “status”=>400}} ]
Running handlers complete
[2026-05-17T19:08:01+08:00] ERROR: Exception handlers complete
Infra Phase failed. 5 resources updated in 14 seconds
[2026-05-17T19:08:01+08:00] FATAL: Stacktrace dumped to /opt/gitlab/embedded/cookbooks/cache/cinc-stacktrace.out
[2026-05-17T19:08:01+08:00] FATAL: —————————————————————————————
[2026-05-17T19:08:01+08:00] FATAL: PLEASE PROVIDE THE CONTENTS OF THE stacktrace.out FILE (above) IF YOU FILE A BUG REPORT
[2026-05-17T19:08:01+08:00] FATAL: —————————————————————————————
[2026-05-17T19:08:01+08:00] FATAL: RuntimeError: letsencrypt_certificate[git.ssorc.tw] (letsencrypt::http_authorization line 6) had an error: RuntimeError: acme_certificate[staging] (letsencrypt::http_authorization line 60) had an error: RuntimeError: ruby_block[create certificate for git.ssorc.tw] (letsencrypt::http_authorization line 112) had an error: RuntimeError: [git.ssorc.tw] Validation failed, unable to request certificate, Errors: [{url: https://acme-staging-v02.api.letsencrypt.org/acme/chall/293165773/1336776933/zmrQwg, status: invalid, error: {“type”=>”urn:ietf:params:acme:error:dns”, “detail”=>”DNS problem: NXDOMAIN looking up A for git.ssorc.tw – check that a DNS record exists for this domain; DNS problem: NXDOMAIN looking up AAAA for git.ssorc.tw – check that a DNS record exists for this domain”, “status”=>400}} ]
A
# 不要讓 GitLab 自動申請 Let’s Encrypt
letsencrypt[‘enable’] = false
Q
為什麼使用了 https 但是 pages 卻 502 Whoops, something went wrong on our end.
A
gitlab-pages 無法驗證 GitLab 主站憑證
sudo tail -n 100 /var/log/gitlab/gitlab-pages/current
看到類似：
x509: certificate signed by unknown authority
或：
failed to connect to internal Pages API
就加這個設定：
gitlab_pages[‘internal_gitlab_server’] = “https://git.ssorc.tw”
gitlab_pages[‘internal_gitlab_server_cert’] = “/etc/gitlab/ssl/ca.crt”
# 或
gitlab_pages[‘internal_gitlab_server’] = “http://127.0.0.1:8080”
留言