Gitlab Docs

📖 Overview

GitLab Docs is your portable, Python-powered sidekick for keeping GitLab CI/CD pipelines well-documented. If your system supports Python 3, you can install it instantly — no complex setup, no platform restrictions.

💡 Why it matters:

Code documentation is crucial.

Pipeline documentation is critical.

As pipelines grow, the what, when, and where of your workflows often get lost.

That’s where GitLab Docs comes in — a simple, elegant CLI tool that automatically generates and updates Markdown documentation for your pipelines, right alongside your code.

✨ Key Features

🛠 Portable — Works anywhere Python 3 runs.

📜 Markdown Output — Friendly for developers, perfect for GitLab README integration.

🔄 Auto-Update Mode — Insert or refresh documentation between customizable markers.

🧩 Multi-Block Support — Maintain different sections for different workflows.

🧪 Dry Run Mode — Preview changes without touching files.

Python

pip3 install --user gitlab-docs

Docker

docker run -v ${PWD}:/gitlab-docs charlieasmith93/gitlab-docs

or

podman run -it -v $(PWD):/gitlab-docs charlieasmith93/gitlab-docs

GITLAB DOCS - .gitlab-ci.yml

Inputs

Variables

Jobs

.TEST:RULES

MEGALINTER

BEHAVE-TESTS

BUMP-VERSION

.BUILD:PYTHON

TEST-BUILD

PUBLISH

DOCKER-BUILD

Command Reference

gitlab-docs

A command line tool to convert your gitlab-ci yml into markdown documentation.

Usage

Usage: gitlab-docs [OPTIONS] COMMAND [ARGS]...

Options

• help:

  • Type: BOOL
  • Default: false
  • Usage: --help

  Show this message and exit.

CLI Help

Usage: gitlab-docs [OPTIONS] COMMAND [ARGS]...

  A command line tool to convert your gitlab-ci yml into markdown
  documentation.

Options:
  --help  Show this message and exit.

Commands:
  generate        Will scan through your gitlab-ci yml and build a markdown...
  get-attributes  Compared to the generate command, the get-attribute...

get-attributes

Compared to the generate command, the get-attribute command allows you to pass the properties you wish to document and produces a markdown table. Args: OUTPUT_FILE (type): description DRY_MODE (type): description GLDOCS_CONFIG_FILE (type): description attributes (type): description json (type): description

Usage

Usage: gitlab-docs get-attributes [OPTIONS]

Options

• attributes:

  • Type: STRING
  • Default: readme.md
  • Usage: --attributes -a

  Pass a comma seperated list of gitlab ci yml attributes

• OUTPUT_FILE:

  • Type: STRING
  • Default: readme.md
  • Usage: --output-file -o

  Output location of the markdown documentation.

• GLDOCS_CONFIG_FILE:

  • Type: STRING
  • Default: .gitlab-ci.yml
  • Usage: --input-config -i

  The Gitlab CI Input configuration file to generated documentation from.

• json:

  • Type: BOOL
  • Default: false
  • Usage: --json -j

  Return results in json format.

• help:

  • Type: BOOL
  • Default: false
  • Usage: --help

  Show this message and exit.

CLI Help

Usage: gitlab-docs get-attributes [OPTIONS]

  Compared to the generate command, the get-attribute command allows you to
  pass the properties you wish to document and produces a markdown table.
  Args:     OUTPUT_FILE (_type_): _description_     DRY_MODE (_type_):
  _description_     GLDOCS_CONFIG_FILE (_type_): _description_
  attributes (_type_): _description_     json (_type_): _description_

Options:
  -a, --attributes TEXT    Pass a comma seperated list of gitlab ci yml
                           attributes

  -o, --output-file TEXT   Output location of the markdown documentation.
  -i, --input-config TEXT  The Gitlab CI Input configuration file to generated
                           documentation from.

  -j, --json BOOLEAN       Return results in json format.
  --help                   Show this message and exit.

dumps

Click-md

Create md files per each command, in format of parent-command, under the --docsPath directory.

Usage

Usage: gitlab-docs dumps [OPTIONS]

Options

• basemodule (REQUIRED):

  • Type: STRING
  • Default: src.gitlab_docs
  • Usage: --baseModule

  The base command module path to import

• basecommand (REQUIRED):

  • Type: STRING
  • Default: gitlab_docs
  • Usage: --baseCommand

  The base command function to import

• docspath (REQUIRED):

  • Type: STRING
  • Default: docs/
  • Usage: --docsPath

  The docs dir path to write the md files

• help:

  • Type: BOOL
  • Default: false
  • Usage: --help

  Show this message and exit.

CLI Help

Usage: gitlab-docs dumps [OPTIONS]

  # Click-md Create md files per each command, in format of `parent-
  command`, under the `--docsPath` directory.

Options:
  --baseModule TEXT   The base command module path to import  [required]
  --baseCommand TEXT  The base command function to import  [required]
  --docsPath TEXT     The docs dir path to write the md files  [required]
  --help              Show this message and exit.

generate

Will scan through your gitlab-ci yml and build a markdown document from the yml.

Usage

Usage: gitlab-docs generate [OPTIONS]

Options

• detailed:

  • Type: BOOL
  • Default: false
  • Usage: --detailed

  Will include workflow and rules from jobs.

• DRY_MODE:

  • Type: BOOL
  • Default: false
  • Usage: --dry-mode -d

  If set will disable documentation from being written

• OUTPUT_FILE:

  • Type: STRING
  • Default: readme.md
  • Usage: --output-file -o

  Output location of the markdown documentation.

• GLDOCS_CONFIG_FILE:

  • Type: STRING
  • Default: .gitlab-ci.yml
  • Usage: --input-config -i

  The Gitlab CI Input configuration file to generated documentation from.

• help:

  • Type: BOOL
  • Default: false
  • Usage: --help

  Show this message and exit.

CLI Help

Usage: gitlab-docs generate [OPTIONS]

  Will scan through your gitlab-ci yml and build a markdown document from
  the yml.

Options:
  --detailed               Will include workflow and rules from jobs.
  -d, --dry-mode           If set will disable documentation from being
                           written

  -o, --output-file TEXT   Output location of the markdown documentation.
  -i, --input-config TEXT  The Gitlab CI Input configuration file to generated
                           documentation from.

  --help                   Show this message and exit.

GITLAB DOCS - .gitlab-ci.yml

Inputs

+-------------+---------------------------+-------------+----------+--------+ | Key | Value | Description | Options | Expand | +-------------+---------------------------+-------------+----------+--------+ | environment | {'default': 'production'} | ❌ | ❌ | true | | job-stage | {'default': 'test'} | ❌ | ❌ | true | +-------------+---------------------------+-------------+----------+--------+

Variables

+-------------+----------------+-------------+----------+--------+ | Key | Value | Description | Options | Expand | +-------------+----------------+-------------+----------+--------+ | APPLICATION | gitlab-docs | ❌ | ❌ | true | | OUTPUT_FILE | GITLAB-DOCS.md | ❌ | ❌ | true | +-------------+----------------+-------------+----------+--------+

Jobs

.TEST:RULES

+---------------+-------------------------------------------------------+ | Attribute | Value | +---------------+-------------------------------------------------------+ | rules | ['if': '$CI_PIPELINE_SOURCE == "merge_request_event"' | | | 'if': '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'] | | stage | test | +---------------+-------------------------------------------------------+

MEGALINTER

+-------------------+--------------------------------+ | Attribute | Value | +-------------------+--------------------------------+ | allow_failure | True | | extends | ['.test:rules'] | | image | oxsecurity/megalinter-ci_light | +-------------------+--------------------------------+

+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+ | Attribute | Key | Value | +-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+ | variables | DEFAULT_WORKSPACE | $CI_PROJECT_DIR | +-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+

BEHAVE-TESTS

+---------------+---------------------+ | Attribute | Value | +---------------+---------------------+ | extends | ['.test:rules' | | | '.poetry:install'] | +---------------+---------------------+

+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+ | Attribute | Key | Value | +-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+ | variables | POETRY_VIRTUALENVS_CREATE | false | +-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+

BUMP-VERSION

+---------------+---------------------------------------+ | Attribute | Value | +---------------+---------------------------------------+ | image | python:3.12.11 | | rules | ['if': '$CI_COMMIT_BRANCH == "main"'] | | stage | .post | +---------------+---------------------------------------+

.BUILD:PYTHON

+-----------------+---------------------+ | Attribute | Value | +-----------------+---------------------+ | environment | release | | extends | ['.poetry:install'] | | stage | build | +-----------------+---------------------+

TEST-BUILD

+---------------+-------------------+ | Attribute | Value | +---------------+-------------------+ | extends | ['.build:python'] | +---------------+-------------------+

PUBLISH

+---------------+-------------------------------------------------+ | Attribute | Value | +---------------+-------------------------------------------------+ | extends | ['.poetry:install'] | | id_tokens | 'PYPI_JWT': 'aud': 'https://pypi.org' | | rules | ['if': '$CI_COMMIT_REF_NAME == $CI_COMMIT_TAG'] | | stage | publish | +---------------+-------------------------------------------------+

DOCKER-BUILD

+---------------+-------------------------------------------------+ | Attribute | Value | +---------------+-------------------------------------------------+ | image | docker:latest | | rules | ['if': '$CI_COMMIT_REF_NAME != $CI_COMMIT_TAG'] | | services | ['docker:dind'] | | stage | build | | tags | ['gitlab-org-docker'] | +---------------+-------------------------------------------------+