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

Question

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?

Gaullism

Answer 1

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
…

Ilium

OK, so I've tried that here and the result is a 404 on index.html. I also tried using the $CI_PAGES_URL and as you can see here that also has problems, both with the 404 and with the relative links. The mkdocs.yml is here – Gaullism

I'm also wondering whether route maps are necessary? – Gaullism

And browsing manually to the artifact, this is the URL we need: https://snim2-test-group.gitlab.io/-/snim2-test-subgroup/review-app-tester/-/jobs/463630423/artifacts/public/index.html but this is $CI_PROJECT_NAMESPACE: snim2-test-group/snim2-test-subgroup and this is $CI_PAGES_URL: https://snim2-test-group.gitlab.io/snim2-test-subgroup/review-app-tester. So, I suspect this just isn't possible :( – Gaullism

@Gaullism do you still have the review app URL that was produced for this CI job? I can't see it anymore since you've updated the MR, but internal links and CSS seem to work for that build, and this URL should have been the review app URL in that run. – Ilium

@Gaullism ah, I see in your debug trace that CI_PROJECT_NAMESPACE indeed contains both group and subgroup – I wasn't aware of this. In this case, my recommendation is to simply hard-code the subgroup, I've updated my answer. The downside is that you'll need to adapt the .gitlab-ci.yml slightly when using it in a project in a different subgroup. – Ilium

OK, this is better, and the index.html maps correctly to this page but if you click on the link to the Subpage that doesn't work, because the subpage/ URL does not map to subpage/index.html. I'm not sure whether this is fixable, with route maps or otherwise. – Gaullism

@Gaullism have you tried use_directory_urls: false in your mkdocs.yml? – Ilium

I did not, but the result is here – Gaullism

@Gaullism This one works for me – Ilium

The »view app« button in the MR also works for me now. – Ilium

I think you're right. This is annoyingly fiddly. Thanks for your help! – Gaullism

it does require quite a few things to be just right ;-) glad it works now – Ilium