Allow testing documentation pages via MRs

fjgarlin → closed merge request !149

Won't fix because it's not possible with our instance setup.

In #3515276-7: Add documentation .md files to test the pages job → #7-9 you showed me the setting for switching between the real url and a generated one with digits in. When I was testing the doc pages build on 📌 Formatting fixes Active my MR runs were built to that url, which was perfect as it did not alter the live site. Is there a way we change that setting within a pipeline? Or can we document the feature, to allow a maintainer to swap the setting when they are working on changes to the .md files? The added digits in the url are constant within a project, so that url is 'fixed' for all testing, not random each time.

my MR runs were built to that url, which was perfect as it did not alter the live site
Let's experiment with that. If the main project has a URL and the MR another, and they don't overwrite one another, we can document it. But let's test it and be sure of that first.

I haven't seen nor found a variable that we could set up. There is an API which we might be able to use.

Question: if we choose the unique domains, are the page URLs created in the main project or in the fork project? I guess it depends on where the MR is created (which depending on the permissions within the project is either canonical project or fork).

Here is what I have seen so far, maybe we can work out from this:

Coding Standards
📌 Formatting fixes Active
1. MR run by maintainer writes to the 'real' site
https://project.pages.drupalcode.org/coding_standards/

2. Same MR pipeline by non-maintainer (me)
https://coding-standards-3527545-5994d4.pages.drupalcode.org
This has the issue fork and the extra digits

Gitlab Templates Downstream
📌 Add documentation .md files to test the pages job Active
3. MR run by maintainer with the 'use unique domain' box ticked
https://gitlab-templates-downstream-1d35fd.pages.drupalcode.org/
This looks like 2 but without the issue number

4. Then by maintainer after unticking the box
https://project.pages.drupalcode.org/gitlab_templates_downstream/
This is the same as 1.

This does not cover all the scenarios. We could invite a non-maintainer to run MR pipeline in GTD, and I assume the result would be like 2 if the 'unique domain' is not ticked. Then find out what happens when it is ticked.

Here is the mkdoc API reference https://www.mkdocs.org/dev-guide/api/ but I don't know where to start with that.

We could invite a non-maintainer to run MR pipeline in GTD
If you want, we can revoke my access to the project temporarily, then I can create an issue/MR and see.

Happy to coordinate for this.

OK that's sounds like a good idea, as you already know what we are trying to do. I have just done it.

Issue created here 📌 Update pages test Active . Creating an MR with doc changes now.

The URL to the docs in the issue description no longer works, and I found this https://forum.gitlab.com/t/modfy-the-deployed-gitlabpages-in-ci-rather-t..., so maybe the way this works has changed.

Worth testing the environments option to see if we get this on our instance.

Ignore the above forum post. That's from 2019 and it doesn't seem to be available in the project settings.

Tho the environments feature does exist: https://docs.gitlab.com/ci/environments/

Not sure if this is something that we can leverage here.

There is also the --site-dir public parameter in mkdocs. If this could be changed for MR runs, would that be possible? I think the 'pages:deloy' may be expecting 'public' because I did a quick test with a different directory. But is that something we can explore?

You can tell GitLab pages which folder to look at: https://docs.gitlab.com/user/project/pages/introduction/#customize-the-d...
So commits to the default branch could be "public" whereas MRs could be a unique folder.

That might be a good way to get things going. We'd need to test again what happens with maintainer vs non-maintainer.

This is great news. I'll work on a solution to have that folder as a variable, which can hopefully be changed in the pipeline 'pages' script, so that 'pages:deploy' can use it.