How to publish html report

Question

I am using a GitLab pipeline to run some tests and produce a coverage report.

What I would like to do is be able to publish the produced coverage folder (that includes an html page and an src folder) to some internal GitLab static page, viewable by some team members.

I am aware of the gitlab pages concept, but the steps indicate that I have to use a static site generator for this purpose.

My questions are the following:

• is the concept usable only when publishing on the official GitLab website (gitlab.io) or can I make use of my on-prem GetLab installation (i.e. so that my pages are available in my.local.gitlab.server/mynamespace/thepagesproject)?

• can I just upload an index.html file with the folder of its contents and make it accessible?

• what is the optimal way of making use of an EXISTING project, so that just to add some html pages to it (ideally I would like to avoid creating a new project just for this purpose)

Howler

I hope that I managed to answer your question. Please let me know if there's anything I missed. If not, you could consider marking mine as the accepted answer. – Sogdiana

Answer 1

Can I use GitLab Pages on self-hosted instance?

Yes, GitLab Pages works on self-hosted instances. You may need to register a wildcard domain name for *.pages.<your-gitlab-domain-name>, and generate SSL certs if you are running gitlab over https only.

Once you have a domain, edit /etc/gitlab/gitlab.rb and add the extra settings, and run a gitlab-ctl reconfigure (leave out the pages_nginx settings if you are running over http only):

gitlab_pages['enable'] = true
pages_external_url "https://pages.<your-gitlab-domain-name>"
pages_nginx['redirect_http_to_https'] = true
pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/pages.<your-gitlab-domain-name>.crt"
pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/pages.<your-gitlab-domain-name>.key"

Once that is done you will be able to access per-project pages via <group>.pages.<your-gitlab-domain-name>/<project>

Can I upload whatever I want to pages?

Yes. Each GitLab CI job can create content to publish in GitLab pages by writing it into a public folder, and registering public as an artifact directory. A final pages job should be added to the CI pipeline which causes the pages content to be published (overwriting anything that was there before). All the content of the public directory will be available via the <group>.pages.<your-gitlab-domain-name>/<project> URL, which means you have full control over content.

Note that the pages job in CI doesn't need to have any script, it just needs to be present with the job name "pages". This is a magic job name that triggers the pages publish. You may want to add job restrictions so that this only runs on master branch pipelines.

Can I add pages publish to an existing project?

Yes. Any steps that create content you want to publish should write the content to a public subdirectory, and register the public directory as an artifact directory.

my job:
  stage: build
script:
  - echo "Do some things and write them to public directory" > public/index.html
artifacts:
  paths:
  - public
    expire_in: 2 weeks

Note: I like to add expire_in: 2 weeks to limit the length of time artifacts are kept around. Once the pages have been published the artifacts aren't really needed.

Finally you need to add a pages job to trigger the pages publish:

# This job does nothing but collect artifacts from other jobs and triggers the pages build
# The artifacts are picked up by the pages:deploy job.
pages:
  stage: deploy
  script:
    - ls -l public
  artifacts:
    paths:
      - public
  only:
    - master

Usually you will only want to publish on master branch, but you have freedom to choose when you want the pages publish to run. It is important to note that when the pages publish runs it will fully replace any content that was previously published, so you can't append to existing content (although there are some hacks that allow you to achieve something similar).

Sogdiana

Could you elaborate on the hacks to update existing pages? – Montagnard

As mentioned, you can't append content, but you can fake it by downloading the public artifact content from the previous release, meaning you can then append on top of that, achieving the same result. I need to look at my code, but I think I use curl and the GitLab API to fetch artifacts. If you think this would be a useful addition I can include more detail. IMHO the end result is over complicated, and I would welcome a simpler way to do this. – Sogdiana