Search code examples
gitlabmkdocsgitlab-pages

Can GitLab pages be used for review apps on a mkdocs project?

This answer by @joki to a previous question suggests that it is possible to deploy each active branch in a GitLab repo to a dynamic environment, by giving browsable artifacts a public URL.

Trying this out with a mkdocs material project, I've found two issues.

Firstly, if the GitLab repo is within a group or a subgroup the URLs in the .gitlab-ci.yml file needs to be something more like this:

    environment:
        name: review/$CI_COMMIT_REF_NAME
        url: "$CI_PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/public/index.html"
        auto_stop_in: 1 week
    variables:
        PUBLIC_URL: "$CI_PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/public/"

Secondly, relative links within the site don't work well, leading to a lot of 404 errors, and the loss of things like style files. Possibly the URLs above are not right, or maybe the site_url in mkdocs.yml needs changing to something like:

site_url: !!python/object/apply:os.getenv ["CI_ENVIRONMENT_URL"]

however, neither of these quite worked for me.

A minimal MR with a very small deployment and review app can be found here.

Does anyone have a working recipe for mkdocs review apps?

Solution

  • You can see the URL you need in the »Browse« button of the build step in your pipeline.

    Does this work?

    develop:
    artifacts:
        paths:
          - public

    environment:
        name: Develop
        url: "https://$CI_PROJECT_NAMESPACE.gitlab.io/-/snim2-test-subgroup/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html"

    script: |
        # whatever

    stage: deploy

    variables:
        PUBLIC_URL: "/-/snim2-test-subgroup/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public"

    You'll also need your change to mkdocs.yml to actually use the PUBLIC_URL, and make sure it's used everywhere that absolute internal links are generated:

    site_url: !!python/object/apply:os.getenv ["PUBLIC_URL"]
use_directory_urls: false
…