Activating Gitlab Pages directly on your Gitlab Server

If you have installed Gitlab to use a subdomain such as gitlab.example.com you can activate Gitlab Pages on the same server quite easily:

• Create a DNS entry for your pages subdomain to point to the same IP address. (eg.: pages.example.com A <YOUR-IP>)
• Meanwhile install Certbot (eg.: sudo apt install certbot).
• A couple of minutes after creating the DNS record, your new subdomain should be resolved. So now let’s obtain the certificate:
  
  certbot certonly --standalone -d pages.example.com
• Now convert the certficates into the format Gitlab expects and place them in the folder that Gitlab actually searches in:

openssl x509 -in /etc/letsencrypt/live/pages.example.com/fullchain.pem -out /etc/gitlab/ssl/pages.example.com.crt 
openssl pkey -in /etc/letsencrypt/live/pages.example.com/privkey.pem -out /etc/gitlab/ssl/pages.example.com.key

• Now, adjust your configuration in /etc/gitlab/gitlab.rb. In order not having to configure a wildcard domain, i chose to remove the namespace from the domain. This way, the final URL will be https://pages.example.com/<vendor|group>/<project>.

pages_external_url "https://pages.example.com/"
gitlab_pages['enable'] = true
gitlab_pages['access_control'] = 'internal'
gitlab_pages['namespace_in_path'] = true

• Finally reconfigure Gitlab with sudo gitlab-ctl reconfigure

I did actually run into OAuth errors, initially. This was caused by Gitlab Settings in the Admin area. Head to Admin > Applications and click the Edit icon next to Gitlab Pages. Here I found a callback URL which pointed to subdomain, that I didn’t set up. The solution was to adjust this URL to the new schema (without the namespace as part of the URL). The OAuth error page i saw, actually had a redirect query parameter, which told me exactly what the URL in this settings page needed to be. After adjusting this URL everything worked as expected. In my case, I wanted the static pages to be private and for internal use, so that only logged-in users can see them.

Deploy your static pages

There are many pre-made templates for static page deployments you can choose from when you create a new .gitlab-ci.yml file in your project. An example

image: node:22
pages:
  needs: []
  stage: deploy
  cache:
    paths:
      - node_modules/
  script:
    - yarn install
    - yarn docs:build
  artifacts:
    paths:
      - public/docs
    expire_in: 1 week
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - docs/**
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true

Conclusion

Activating Gitlab Pages in Gitlab is pretty easy. You get private/public static pages with an authorziation mechanism included. Hosted close to your code, on-premise without the need for additional environments. It’s especially useful when you want to add some Documentation or Design System to your projects.

Next steps

You will also need to make sure, that the certificate for your pages.example.com domain is renewed and converted to .crt and .key formats upon renewal.