One of the things I start to use more and more are private Julia registries, which are really easy to set up and make it much easier to deploy packages which are very experiment specific and not worth to pollute the general registry.
We use our own self-hosted GitLab instance with a heavy multi-rack CI infrastructure with our own GitLab runners and we are very happy with that solution, but…
There is currently no way to host or store version specific documentation generated by e.g.
Documenter.jl via the GitLab CI, which means that we can only deploy a single version of the documentation, being it the latest tag or generated from the latest commit. For early prototypes we usually go with the latest commit on the
main branch and for more mature Julia packages we restrict it to
The main problem for that is the way the GitLab CI pages deployment works. It simply uploads (and replaces) the folder called
public/ in a job which needs to be called
pages. That’s it:
- mkdir public
- echo hello world > public/index.html
GitLab offers a
cache functionality, which allows to store data of a job in a persistent place and it gets extracted every time a job is executed again, so technically one could utilise that, but the problem is that this cache can be invalidated with a single button and it cannot be “protected” whatsoever. There is also no way to wipe the cache for a specific job, so even discipline will not help. The “clear runner caches” clears the caches for all jobs of a projects. It’s needless to say that this button has to be pressed here and there when things break (we use caches to limit traffic to package repositories and computation time by caching build products).
In the GitHub Actions universe, the situation is much nicer. GitHub deals with the deployment of “pages” in a fundamentally different way and maintains an extra branch (usually) called
gh-pages like this one: GitHub - JuliaHEP/UnROOT.jl at gh-pages which is modified (by
Documenter.jl) each time a deployment is triggered to update
versions.js and create a new folder for the tag and replace the symlinks for the
Now my question: does anyone have a working solution or an idea how to bring multiple version doc hosting to the GitLab universe?
I guess the only way is to mimic the extra-branch-approach of GitHub by implementing the procedure in
Documenter.jl and then create a GitLab CI job template, but before I dive into that I was curious if anyone has done anything in that direction
Ahhm… I just found a deploy configuration for
GitLab: Hosting Documentation · Documenter.jl
I have never seen that before let me try that.
OK I few things I have found so far (I have used the
PkgTemplates.jl with the GitLab plugin):
- The default Julia version 1.0 will not work, 1.6+ is needed to do the deployment (building docs works also with 1.0 though)
git is not installed in the default
julia:1.6 Docker image so it needs to be installed in each job, or better: use another image where git is already pre-installed
- GitLab does not have a project specific scope for SSH keys, which is needed for the modification of the
gh-pages branch to store the versioned docs by
Documenter.jl (the base64-encoded private key has to be defined as a CI variable named
DOCUMENTER_KEY). This is kind of awkward since it means that one of the users with write-access has to put the public key in their own account. Everyone with maintainer access has access to that SSH key-pair (and therefore to all repos of that user)
- The default URL for the documentation points to
gitlab.io (also the badge in the
README.md), so for self-hosted GitLab servers the URL is incorrect. This needs to be changed manually in
- I found that the default branch is still
master in a few places, I think those came from
Documenter.jl but the errors were clear and the fix was overriding the defaults.
I’ll gather all the issues and try to find time to make PRs to
Documenter.jl if needed.
For now it seems to work with a bit of fiddling and accepting some serious security issues with the account-bound SSH-keypair
You can get started by adding
deploydocs() to your
repo = "git.your-institute.com/username/Project.jl",
devbranch = "main",
A tiny update: I still have not managed to get the versions displayed. For whatever reason, the
versions.js does only contain
dev, so creating version tags has no effect on that. The commits to
gh-pages work though via the
Here is the example project I am working on: https://git.km3net.de/tgal/JuliaGitLabPages.jl
The problem is that even if the commits to
gh-pages work, there is no (obvious) way in GitLab to tell pages to use that branch. We would need another
.gitlab-ci.yml or so on that branch, since only the
pages job is able to deploy the docs by declaring the
public/ folder as an artifact.
I created a Git issue to summarise things and try to work on a PR: Deploying docs on GitLab CI with version-selection feature · Issue #2061 · JuliaDocs/Documenter.jl · GitHub
OK, with a bit of fiddling, everything works now. It’s still a manual process but I’ll make a PR to
Documenter.jl which makes it a bit easier. You can read the everything in the issue https://github.com/JuliaDocs/Documenter.jl/issues/2061