Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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?

like image 911
snim2 Avatar asked Mar 04 '20 16:03

snim2


People also ask

What are GitLab review apps?

GitLab Review Apps are staging environments that are automatically created for every branch and/or merge request. They are a collaboration tool built into GitLab that helps take the hard work out of providing an environment to showcase or validate product changes.

How do GitLab pages work?

GitLab always deploys your website from a specific folder called public in your repository. When you create a new project in GitLab, a repository becomes available automatically. To deploy your site, GitLab uses its built-in tool called GitLab CI/CD to build your site and publish it to the GitLab Pages server.

Are GitLab pages free?

With GitLab Pages you can host your static website for free.


1 Answers

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
…
like image 109
joki Avatar answered Oct 09 '22 21:10

joki