6

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?

snim2
  • 4,004
  • 27
  • 44

1 Answers1

4

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
…
joki
  • 6,619
  • 2
  • 22
  • 30
  • OK, so I've tried that [here](https://gitlab.com/snim2-test-group/snim2-test-subgroup/review-app-tester/-/blob/feature-branch/.gitlab-ci.yml) and the result is a 404 on `index.html`. I also tried using the `$CI_PAGES_URL` and as you can see [here](https://snim2-test-group.gitlab.io/snim2-test-subgroup/review-app-tester/-/jobs/463623377/artifacts/public/index.html) that also has problems, both with the 404 and with the relative links. The `mkdocs.yml` is [here](https://gitlab.com/snim2-test-group/snim2-test-subgroup/review-app-tester/-/blob/feature-branch/mkdocs.yml) – snim2 Mar 08 '20 at 16:19
  • I'm also wondering whether [route maps](https://docs.gitlab.com/ce/ci/review_apps/#route-maps-example) are necessary? – snim2 Mar 08 '20 at 16:25
  • 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 :( – snim2 Mar 08 '20 at 17:10
  • @snim2 do you still have the review app URL that was produced for [this CI job](https://gitlab.com/snim2-test-group/snim2-test-subgroup/review-app-tester/-/jobs/463615496)? I can't see it anymore since you've updated the MR, but internal links and CSS seem to work for [that build](https://snim2-test-group.gitlab.io/-/snim2-test-subgroup/review-app-tester/-/jobs/463615496/artifacts/public/index.html), and this URL should have been the review app URL in that run. – joki Mar 08 '20 at 18:20
  • @snim2 ah, I see in your [debug trace](https://gitlab.com/snim2-test-group/snim2-test-subgroup/review-app-tester/-/jobs/463621636) 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. – joki Mar 08 '20 at 18:36
  • OK, this is better, and the `index.html` maps correctly [to this page](https://snim2-test-group.gitlab.io/-/snim2-test-subgroup/review-app-tester/-/jobs/463734560/artifacts/public/index.html) 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. – snim2 Mar 08 '20 at 22:05
  • @snim2 have you tried [`use_directory_urls: false`](https://www.mkdocs.org/user-guide/configuration/#use_directory_urls) in your `mkdocs.yml`? – joki Mar 09 '20 at 13:35
  • I did not, but the result is [here](https://snim2-test-group.gitlab.io/-/snim2-test-subgroup/review-app-tester/-/jobs/463734560/artifacts/public/index.html) – snim2 Mar 09 '20 at 14:43
  • @snim2 [This one](https://snim2-test-group.gitlab.io/-/snim2-test-subgroup/review-app-tester/-/jobs/464531722/artifacts/public/index.html) works for me – joki Mar 09 '20 at 15:43
  • The »view app« button in the MR also works for me now. – joki Mar 09 '20 at 15:50
  • I think you're right. This is annoyingly fiddly. Thanks for your help! – snim2 Mar 09 '20 at 16:10
  • it does require quite a few things to be just right ;-) glad it works now – joki Mar 09 '20 at 16:18