Serve static html pages with Gitlab Pages for each tagged version of a project

Question

I have a code project hosted on a custom gitlab instance. This project is part of a subgroup. We'd like to host static html content, generated by doxygen and similar tools, using Gitlab Pages. Trivial examples work very well, so I believe it's safe to conclude that the general gitlab + gitlab pages setup is fine.

Now I'd like to publish dedicated html pages for each tagged software version. This is due to us using git tags to mark releases, and for each release the related code documentation shall be persistently available.

Here's my .gitlab-ci.yml file trying to accomplish this:

image: alpine:latest

pages:
  stage: deploy
  script:
    - mkdir public
    # Provide a sample "html" page instead of running doxygen
    - echo $CI_PAGES_URL > public/index.html
  artifacts:
    paths:
    - public
  # Desperate attempt:
  environment:
    name: $CI_COMMIT_REF_SLUG
    url: $CI_PAGES_URL/$CI_COMMIT_REF_SLUG
  only:
    - tags

As a result of a gitlab runner executing this script the page is published, but under the "main" project pages URL, not under a dedicated URL related to the tag name / "commit ref slug". The deployment environment is created, too, and I can click "View deployment" (see gitlab deploy environment showing the "View deployment" button), but when doing so I get a 404 error.

I'd appreciate any hints on how to accomplish the described goal.

PS: This might sound related to Deploying GitLab pages for different branches, but I think it is not. Please correct me if I'm wrong.

score 0 · Answer 1 · answered Aug 04 '23 at 19:53

We can adapt the solution from GitLab Pages per branch : the no-compromise hack to serve preview pages to suit your needs.

2 (minor) problems remaining :

the pages space can not grow indefinitely, while your number of release will certainly. So the cleaning job is kept in the solution, and you will have to use it manually when GitLab will refuse to publish more files.
cache is not guaranteed ; you will have to launch again pages jobs on latest releases pipelines when cache disappears or is wiped clean.

pages:
  stage: build
  image: alpine:3.18
  cache:
    key: gitlab-pages
    paths: [public]
  before_script:
    # default available 'tree' app in alpine image does not work as intended
    - apk add tree
    - mkdir -p public/$CI_COMMIT_REF_SLUG && ls public
    - rm -rf public/$CI_COMMIT_REF_SLUG || true # remove last version of current tag
  script:
    - ./generate-my-html.sh --output build-docs || true # insert here your code that generates documentation
    - mv --verbose build-docs public/$CI_COMMIT_REF_SLUG
    - cd public
    - tree -d -H '.' -L 1 --noreport --charset utf-8 -T "Releases" -o index.html # generate a root HTML listing all releases for easier access
  artifacts:
    paths: [public]
    expire_in: 1h
  rules:
    - if: $CI_COMMIT_TAG

pages-clean-release:
  stage: build
  image: alpine:3.18
  cache:
    key: gitlab-pages
    paths: [public]
  variables:
    FOLDER_TO_DELETE: $CI_COMMIT_REF_SLUG # an indirection to allow arbirtraty deletion when launching this job
  script:
    - rm -rf public/$FOLDER_TO_DELETE
  when: manual
  rules:
    - if: $CI_COMMIT_TAG

Serve static html pages with Gitlab Pages for each tagged version of a project

1 Answers1