{"id":20915810,"url":"https://github.com/brainelectronics/lightweight-versioned-gitlab-pages","last_synced_at":"2025-07-02T07:06:52.195Z","repository":{"id":69601617,"uuid":"597832366","full_name":"brainelectronics/lightweight-versioned-gitlab-pages","owner":"brainelectronics","description":"  Enable GitLab pages to provide documentation for multiple versions","archived":false,"fork":false,"pushed_at":"2023-02-14T18:15:37.000Z","size":108,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-05T07:00:36.292Z","etag":null,"topics":["gitlab","gitlab-pages","pages","versioning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brainelectronics.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-05T19:12:31.000Z","updated_at":"2023-12-12T10:53:50.000Z","dependencies_parsed_at":"2023-06-11T06:45:22.780Z","dependency_job_id":null,"html_url":"https://github.com/brainelectronics/lightweight-versioned-gitlab-pages","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/brainelectronics/lightweight-versioned-gitlab-pages","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Flightweight-versioned-gitlab-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Flightweight-versioned-gitlab-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Flightweight-versioned-gitlab-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Flightweight-versioned-gitlab-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brainelectronics","download_url":"https://codeload.github.com/brainelectronics/lightweight-versioned-gitlab-pages/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brainelectronics%2Flightweight-versioned-gitlab-pages/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263091025,"owners_count":23412344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gitlab","gitlab-pages","pages","versioning"],"created_at":"2024-11-18T16:18:26.460Z","updated_at":"2025-07-02T07:06:52.176Z","avatar_url":"https://github.com/brainelectronics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lightweight Versioned GitLab Pages\n\n[![Downloads](https://pepy.tech/badge/lightweight-versioned-gitlab-pages)](https://pepy.tech/project/lightweight-versioned-gitlab-pages)\n[![pipeline status](https://gitlab.com/brainelectronics/lightweight-versioned-gitlab-pages/badges/main/pipeline.svg)](https://gitlab.com/brainelectronics/lightweight-versioned-gitlab-pages/-/commits/main)\n[![Documentation Status](https://readthedocs.org/projects/lightweight-gitlab-pages/badge/?version=latest)](https://lightweight-gitlab-pages.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gitlab/brainelectronics/lightweight-versioned-gitlab-pages/branch/main/graph/badge.svg)](https://codecov.io/gitlab/brainelectronics/lightweight-versioned-gitlab-pages)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/lightweight-versioned-gitlab-pages)\n[![License: MIT](https://img.shields.io/gitlab/license/brainelectronics/lightweight-versioned-gitlab-pages?color=green)](https://opensource.org/licenses/MIT)\n\nGenerate index page with links to all previously archived folders during a tag\nbuild.\n\nThis repo developed in and mirrored from [GitLab brainelectronics](https://gitlab.com/brainelectronics/lightweight-versioned-gitlab-pages).\nPlease raise your issues and submit your pull requests/merge requests there.\n\n---------------\n\n## Installation\n\n```bash\npip install lightweight-versioned-gitlab-pages\n```\n\n## Documentation\n\n📚 The latest documentation is available at\n\n- [Lightweight versioned GitLab Pages GitLab Pages](https://brainelectronics.gitlab.io/lightweight-versioned-gitlab-pages)\n- [Lightweight versioned GitLab Pages ReadTheDocs](https://lightweight-gitlab-pages.readthedocs.io/en/latest/)\n\n## Reasoning\n\nGitLab offers the possibility to create or place a folder named `public` in the\nroot of the repo. The contents of this folder are then displayed by\n[GitLab pages](https://docs.gitlab.com/ee/user/project/pages/) and is\naccessible from outside the repo via a custom URL.\n\nFor this package, the URL is\n[`https://brainelectronics.gitlab.io/-/lightweight-versioned-gitlab-pages`](https://brainelectronics.gitlab.io/lightweight-versioned-gitlab-pages).\nThis is also the location of the (latest) documentation for this package.\nSince only only one \"thing\" can be displayed there, usually only the most\nrecent content is available at this URL. This is where this package is supposed to help.\n\n## Usage\n\nIt is assumed that only tagged states of the documentation or other content\nwill be displayed on the GitLab Pages web page, see also chapter Limitations.\n\nFor interaction with GitLab the\n[`python-gitlab`](https://python-gitlab.readthedocs.io/en/stable/) package is\nused.\n\nA unique project ID must be specified with `--project-id`.\nThis ID can be found at the top of each repo. For this repository it is\n`43170198`.\n\nThe second mandatory parameter is `--job-name`. This is the name of the job\nthat generates, for example, the documentation or other content that will be\ndisplayed via the GitLab pages web page.\n\nThe generated `index.html` is placed in a folder named `public`. By default\nthis folder is created in the same directory from which this script is called.\nA different destination folder can be specified with `--output-dir`. The folder\ndoes not have to exist, it and its possibly needed parent directories will be\ncreated if necessary.\n\nIf a self-hosted GitLab is used, the URL to the instance can be specified with\n`--url` to not restrict this package to GitLab.com only.\n\nIn case the CICD artifacts are not publicly available, the script requires an\nAPI token to make all requests through the API. This token must then be\nspecified via the `--private-token` argument. The token can be generated via\n`Settings -\u003e Access Tokens` and requires `api` scope.\n\n### Help\n\n```bash\ngenerate-versioned-pages --help\n```\n\n### Generate lightweight versioned pages\n\nThe following command will create a folder named `public` at the current\nlocation and place an index HTML file inside.\n\nThis index file contains a simple list of\n[Bootstrap cards](https://getbootstrap.com/docs/5.0/components/card/)\nwith all previously built tags and the URL to the public pages archive files.\n\n```bash\ngenerate-versioned-pages \\\n--project-id 43170198 \\\n--job-name pages\n```\n\nThen use this generated folder in the `pages` job. The job configuration in the\nfile `.gitlab-ci.yml` can look like the following example and is used in that\nway for this package.\n\n```yaml\npages:\n  stage: deploy\n  before_script:\n    - pip install lightweight-versioned-gitlab-pages\n  script:\n    - generate-versioned-pages\n      --project-id ${CI_PROJECT_ID}\n      --job-name generate-docs\n  artifacts:\n    expire_in: never\n    paths:\n      - public\n  only:\n    - main\n```\n\n## How it works\n\nFirst, the available tags of the repo are requested/gathered by the\n[get_project_tags](lightweight_versioned_gitlab_pages.generate.get_project_tags)\nfunction. For each tag, the corresponding pipeline job is requested based on\nthe provided `job-name` argument. The job status must be successful to avoid\nerroneous or currently generated artifacts. For each job, the URL to the index\nfile of the `public` folder is generated, see\n[get_artifact_url](lightweight_versioned_gitlab_pages.generate.get_artifact_url)\nThe generated list of\n[TagInfos](lightweight_versioned_gitlab_pages.generate.TagInfo) will then be\nused to create a simple `index.html` file inside a generated `public` folder,\nunless it is to be generated elsewhere.\nThe template is rendered with [Jinja2](https://github.com/pallets/jinja/).\n\n## Advanced Usage\n\n### Custom index file\n\nTo allow users the usage of a different style index file, the `--template-file`\nis there to help.\n\nBy default the index template file delivered with this package is used for\nrendering. A list of\n[TagInfos](lightweight_versioned_gitlab_pages.generate.TagInfo) and the base\nURL of tags (`tag_base_url`) is handed over to the Jinj2 render function.\n\nThe following informations are availabe for individual usage:\n\n| Name | Type | Description |\n| ---- | ----------------- | -------------------|\n| `tag_base_url` | str | URL to the project tags, e.g. `https://gitlab.com/brainelectronics/lightweight-versioned-gitlab-pages/-/tags/` |\n| `items` | List[TagInfos] | List of TagInfo elements |\n\nEach [TagInfo](lightweight_versioned_gitlab_pages.generate.TagInfo) element\ncontains the following fields\n\n| Name | Type | Description |\n| ---- | ----------------- | -------------------|\n| `tag` | ProjectTag | [GitLab ProjectTag](https://python-gitlab.readthedocs.io/en/stable/api/gitlab.v4.html#gitlab.v4.objects.ProjectTag) |\n| `commit` | ProjectCommit | [GitLab ProjectCommit](https://python-gitlab.readthedocs.io/en/stable/api/gitlab.v4.html#gitlab.v4.objects.ProjectCommit) |\n| `created_at` | datetime | [Datetime object](https://docs.python.org/3/library/datetime.html) with the datetime of the tag creation |\n| `job_id` | int | ID of the Job created the tag |\n| `pages_url` | str | Full URL to the generated public index file of the job |\n| `job_ids` | List[Dict[str, int]] | List of pipeline IDs which ran during the job |\n\n### Custom output directory\n\nSave the rendered index file to a different folder than the default `public`\nfolder in the directory where the script is executed.\n\n```bash\ngenerate-versioned-pages \\\n--project-id 43170198 \\\n--job-name pages \\\n--output-dir somewhere/else\n```\n\nThe folder and it's may required parent directories are automatically\ngenerated. The output file name is fixed as `index.html`\n\n### Version info file\n\nTo get more informations about the used tags, the `--create-version-info-file`\nargument can be used. This will generate a `versions.json` file in the output\ndirectory containing all\n[GitLab ProjectTag](https://python-gitlab.readthedocs.io/en/stable/api/gitlab.v4.html#gitlab.v4.objects.ProjectTag)\nand [GitLab ProjectCommit](https://python-gitlab.readthedocs.io/en/stable/api/gitlab.v4.html#gitlab.v4.objects.ProjectCommit)\nattributes, the Job ID and the Pages URL.\n\n## Limitations\n\n- Only links to tagged and archived data of `public` folders are included in\nthe index\n- Job artifacts must be publicly accessible if no API token is used\n    - Make sure that `CI/CD` is activated and set to `Everyone With Access` at\n    `Settings -\u003e General -\u003e Visibility`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainelectronics%2Flightweight-versioned-gitlab-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrainelectronics%2Flightweight-versioned-gitlab-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainelectronics%2Flightweight-versioned-gitlab-pages/lists"}