Categories
DevOps Documentation git

Deploying Mkdocs with Gitlab CI and Gitlab Pages

Gitlab does not have mkdocs in their prexisting ci/cd templates.

.gitlab-ci.yml

On your repo create a .gitlab-ci.yml file with the following contents:

image: python:3.8-buster

before_script:
  - pip install --upgrade pip && pip install -r requirements.txt

pages:
  stage: deploy
  script:
    - mkdocs build
    - mv site public
  artifacts:
    paths:
    - public
  only:
  - master
  • All Gitlab CI is run in containers – so we supply a base image that has python already.
  • Before running the build we need to ensure the mkdocs python package is available.
  • It uses the pages keyword – a special job on gitlab specifically for serving your static site
  • builds the docs and moves it to the public folder – where gitlab pages servers the static content from
  • Done only on the master branch

Pending / Stuck jobs

After this file is commited the pipeline might be in a stuck state:

This is because you have not specified a gitlab runner to run your continuous integration.

On your repo:

  1. Go to settings -> CI/CD
  2. Expand the Runners Section
  3. Click Enabled Shared runners

If it is still stuck in a pending state, just cancel it and it should work on the next run.

How do we View the Site now

For self hosted pages you need to ensure you have:

  • A shared gitlab runner
  • A wildcard domain record pointing to your gitlab instance eg. *.pages.number1.co.za -> x.x.x.x.

Add the domain to your config at /etc/gitlab/gitlab.rb;

pages_external_url 'http://pages.number1.co.za'

Then reconfigure gitlab:

sudo gitlab-ctl reconfigure

All the information for this is in Pages Administration Article

There should be a link on the project Settings -> pages of the repo.

Reference of Gitlab Pages options

##! Define to enable GitLab Pages
# pages_external_url "http://pages.example.com/"
# gitlab_pages['enable'] = false

##! Configure to expose GitLab Pages on external IP address, serving the HTTP
# gitlab_pages['external_http'] = []

##! Configure to expose GitLab Pages on external IP address, serving the HTTPS
# gitlab_pages['external_https'] = []

##! Configure to enable health check endpoint on GitLab Pages
# gitlab_pages['status_uri'] = "/@status"

##! Configure to use JSON structured logging in GitLab Pages
# gitlab_pages['log_format'] = "json"

# gitlab_pages['listen_proxy'] = "localhost:8090"
# gitlab_pages['redirect_http'] = true
# gitlab_pages['use_http2'] = true
# gitlab_pages['dir'] = "/var/opt/gitlab/gitlab-pages"
# gitlab_pages['log_directory'] = "/var/log/gitlab/gitlab-pages"

# gitlab_pages['artifacts_server'] = true
# gitlab_pages['artifacts_server_url'] = nil # Defaults to external_url + '/api/v4'
# gitlab_pages['artifacts_server_timeout'] = 10

##! Environments that do not support bind-mounting should set this parameter to
##! true. This is incompatible with the artifacts server
# gitlab_pages['inplace_chroot'] = false

##! Prometheus metrics for Pages docs: https://gitlab.com/gitlab-org/gitlab-pages/#enable-prometheus-metrics
# gitlab_pages['metrics_address'] = ":9235"

Sources