Package: lightweight-versioned-gitlab-pages
Lightweight Versioned GitLab PagesGenerate index page with links to all previously archived folders during a tag
build.This repo developed in and mirrored fromGitLab brainelectronics.
Please raise your issues and submit your pull requests/merge requests there.Installationpipinstalllightweight-versioned-gitlab-pagesDocumentation📚 The latest documentation is available atLightweight versioned GitLab Pages GitLab PagesLightweight versioned GitLab Pages ReadTheDocsReasoningGitLab offers the possibility to create or place a folder namedpublicin the
root of the repo. The contents of this folder are then displayed byGitLab pagesand is
accessible from outside the repo via a custom URL.For this package, the URL ishttps://brainelectronics.gitlab.io/-/lightweight-versioned-gitlab-pages.
This is also the location of the (latest) documentation for this package.
Since only only one "thing" can be displayed there, usually only the most
recent content is available at this URL. This is where this package is supposed to help.UsageIt is assumed that only tagged states of the documentation or other content
will be displayed on the GitLab Pages web page, see also chapter Limitations.For interaction with GitLab thepython-gitlabpackage is
used.A unique project ID must be specified with--project-id.
This ID can be found at the top of each repo. For this repository it is43170198.The second mandatory parameter is--job-name. This is the name of the job
that generates, for example, the documentation or other content that will be
displayed via the GitLab pages web page.The generatedindex.htmlis placed in a folder namedpublic. By default
this folder is created in the same directory from which this script is called.
A different destination folder can be specified with--output-dir. The folder
does not have to exist, it and its possibly needed parent directories will be
created if necessary.If a self-hosted GitLab is used, the URL to the instance can be specified with--urlto not restrict this package to GitLab.com only.In case the CICD artifacts are not publicly available, the script requires an
API token to make all requests through the API. This token must then be
specified via the--private-tokenargument. The token can be generated viaSettings -> Access Tokensand requiresapiscope.Helpgenerate-versioned-pages--helpGenerate lightweight versioned pagesThe following command will create a folder namedpublicat the current
location and place an index HTML file inside.This index file contains a simple list ofBootstrap cardswith all previously built tags and the URL to the public pages archive files.generate-versioned-pages\--project-id43170198\--job-namepagesThen use this generated folder in thepagesjob. The job configuration in the
file.gitlab-ci.ymlcan look like the following example and is used in that
way for this package.pages:stage:deploybefore_script:-pip install lightweight-versioned-gitlab-pagesscript:-generate-versioned-pages--project-id ${CI_PROJECT_ID}--job-name generate-docsartifacts:expire_in:neverpaths:-publiconly:-mainHow it worksFirst, the available tags of the repo are requested/gathered by theget_project_tagsfunction. For each tag, the corresponding pipeline job is requested based on
the providedjob-nameargument. The job status must be successful to avoid
erroneous or currently generated artifacts. For each job, the URL to the index
file of thepublicfolder is generated, seeget_artifact_urlThe generated list ofTagInfoswill then be
used to create a simpleindex.htmlfile inside a generatedpublicfolder,
unless it is to be generated elsewhere.
The template is rendered withJinja2.Advanced UsageCustom index fileTo allow users the usage of a different style index file, the--template-fileis there to help.By default the index template file delivered with this package is used for
rendering. A list ofTagInfosand the base
URL of tags (tag_base_url) is handed over to the Jinj2 render function.The following informations are availabe for individual usage:NameTypeDescriptiontag_base_urlstrURL to the project tags, e.g.https://gitlab.com/brainelectronics/lightweight-versioned-gitlab-pages/-/tags/itemsList[TagInfos]List of TagInfo elementsEachTagInfoelement
contains the following fieldsNameTypeDescriptiontagProjectTagGitLab ProjectTagcommitProjectCommitGitLab ProjectCommitcreated_atdatetimeDatetime objectwith the datetime of the tag creationjob_idintID of the Job created the tagpages_urlstrFull URL to the generated public index file of the jobjob_idsList[Dict[str, int]]List of pipeline IDs which ran during the jobCustom output directorySave the rendered index file to a different folder than the defaultpublicfolder in the directory where the script is executed.generate-versioned-pages\--project-id43170198\--job-namepages\--output-dirsomewhere/elseThe folder and it's may required parent directories are automatically
generated. The output file name is fixed asindex.htmlVersion info fileTo get more informations about the used tags, the--create-version-info-fileargument can be used. This will generate aversions.jsonfile in the output
directory containing allGitLab ProjectTagandGitLab ProjectCommitattributes, the Job ID and the Pages URL.LimitationsOnly links to tagged and archived data ofpublicfolders are included in
the indexJob artifacts must be publicly accessible if no API token is usedMake sure thatCI/CDis activated and set toEveryone With AccessatSettings -> General -> Visibility