gitlab-pages-upload

Publish versioned static HTML documentation to GitLab Pages with a single command.

If you have prebuilt HTML documentation (from Sphinx, MkDocs, or any other tool), this CLI uploads it to GitLab Pages—requiring only a GitLab.com account and a personal access token. No CI/CD configuration needed on your end.

Installation

pip install gitlab-pages-upload

Or with uv:

uv pip install gitlab-pages-upload

Quick Start

1. Set your GitLab token:

export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

2. Upload your docs:

gitlab-pages-upload --project my-project --doc-version 1.2.3 --html ./site

Usage

gitlab-pages-upload [OPTIONS]

Required:
  --html, -H PATH         Path to HTML documentation (directory or .zip file)

Project/Version (mutually exclusive):
  --auto, -a              Auto-detect project and version from zip filename
  --project, -p NAME      Project name (required unless --auto)
  --doc-version, -V VER   Version (required unless --auto)

Optional:
  --force, -f             Overwrite existing version if it already exists
  --set-latest, -l        Also copy docs to 'latest/' directory
  --group, -g GROUP       GitLab group (default: docs)
  --gitlab-url, -u URL    GitLab instance URL (default: https://gitlab.com)
  --config, -c FILE       Path to JSON configuration file
  --verbose, -v           Display verbose output (use twice for debug)

Examples

Auto-detect from zip filename

# Detects project=myproject, version=1.2.3 from filename
gitlab-pages-upload --auto -H ./myproject-1.2.3-docs.zip --set-latest

Explicit project and version

gitlab-pages-upload -p cal-mkdocs -V 1.2.3 -H ./site

Upload and set as latest

gitlab-pages-upload -p cal-mkdocs -V 1.2.4 -H ./site --set-latest

Custom GitLab instance

gitlab-pages-upload -p my-project -V 1.0.0 -H ./docs \
    --gitlab-url https://gitlab.example.com \
    --group my-team/docs

Using a config file

gitlab-pages-upload -p my-project -V 1.0.0 -H ./docs -c config.json

Example config.json:

{
    "gitlab_url": "https://gitlab.example.com",
    "group": "documentation"
}

Authentication

Create a GitLab Personal Access Token with these scopes:

• api - for project/group creation via API
• write_repository - for git push

Set it as an environment variable:

export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Or in a config file:

{
    "token": "glpat-xxxxxxxxxxxxxxxxxxxx"
}

How It Works

1. Creates GitLab project if it doesn't exist (private repo with public Pages)
2. Clones the project (or initializes if empty)
3. Copies HTML files to public/<version>/
4. Optionally copies to public/latest/ with --set-latest
5. Creates root redirect to latest/ when --set-latest is used
6. Writes .gitlab-ci.yml for GitLab Pages
7. Commits and pushes to GitLab
8. GitLab CI/CD automatically deploys to Pages

Repository Layout

The tool maintains this structure in the GitLab repository:

public/
  index.html       # redirect to latest/ (only if --set-latest used)
  1.2.3/
    index.html
    ...
  1.2.4/
    index.html
    ...
  latest/          # only if --set-latest used
    index.html
.gitlab-ci.yml

Safety Features

• Version protection: Refuses to overwrite existing versions unless --force is specified
• Preserves old versions: Only the specified version directory is modified
• No force push: Uses normal git push (not force push)
• Token redaction: Tokens are never logged or displayed in error messages

Requirements

• Python 3.12+
• Git (for clone/push operations)
• GitLab Personal Access Token with api and write_repository scopes

Development

# Set up development environment
make dev

# Run linting and type checking
make check

# Auto-format code
make format

# Build wheel and docs
make build

Publishing

Publishing requires cal-publish-python configuration. See the cal-publish-python documentation for setup.

# Build first
make build

# Publish wheel to PyPI and docs to GitLab Pages
make publish

Licence

MIT License — Copyright 2026 Cyber Assessment Labs