Gitstrings - Beta (inline YAML)¶

Gitstrings turns decorated YAML into marker-delimited markdown tables (like generate), without overwriting the rest of your README.

Two input modes¶

For CI files, only the annotated fragment is read (for example the variables: map stops before the next top-level key such as image:).

# Scan decorators in pipeline YAML; default output README.md in the same directory
gitlab-compliance document gitstrings -i .gitlab-ci.yml

# Explicit output markdown
gitlab-compliance document gitstrings -i .gitlab-ci.yml -o README.md

When to use¶

Use gitstrings for documented fragments (inputs, variables, small job snippets). Use generate for a full pipeline reference.

Quick start¶

Add gitstrings markers once where generated tables should appear:

<!-- gitlab-compliance-gitstrings-opening-auto-generated -->
<!-- gitlab-compliance-gitstrings-closing-auto-generated -->

Annotate .gitlab-ci.yml (or use markdown fences), then run:

gitlab-compliance document gitstrings -i .gitlab-ci.yml
gitlab-compliance document gitstrings -i README.md
gitlab-compliance document gitstrings -i docs/snippets.md -o README.md
gitlab-compliance document gitstrings -i .gitlab-ci.yml --dry-mode

Authoring in .gitlab-ci.yml¶

# @title Pipeline inputs
# @description
#   Inputs for component consumers.
# @render inputs
# @output README.md
spec:
  inputs:
    job-stage:
      default: test
      description: Stage for test jobs.

Authoring fenced blocks (markdown)¶

Only fences tagged yaml gitstrings are processed. Ordinary ```yaml blocks are ignored.

```yaml gitstrings
# @title Variables
# @render variables
variables:
  APPLICATION: my-app

```

Directives¶

Multi-line descriptions¶

Fragment prose (above tables):

# @description
#   Use these inputs when including this component.
# @render inputs
spec:
  inputs:
    job-stage:
      default: test

Per-field (GitLab YAML block scalars become <br> in table cells):

variables:
  DEPLOY_ENV:
    value: production
    description: |
      Target environment.
      Use staging on feature branches only.

Includes fragment¶

Document the pipeline include list as a table (local, project, component, remote, template):

# @title Pipeline includes
# @description
#   External and local CI fragments consumed by this configuration.
# @render includes
include:
  - local: gitlab-ci/hidden.jobs.yml
  - project: my-group/my-project
    ref: 1.2.3
    file: ci/workflow.yml

Use @render includes for legacy fragment mode (the fenced include list in the block). Use @render include for path mode on the top-level include key — with -i set to a CI YAML file, that resolves the full file’s include list (not only the annotated fragment).

--include-nested scope (on disk only)¶

Requirements for nesting:

• -i must be the root CI YAML file (.yml / .yaml) so local: paths resolve on disk.
• Markdown-only scans (fences in README) document only the fenced include list; nesting does not apply.

Without --include-nested, only include entries in the annotated fragment are shown (or the full top-level include list when using path include on a CI file).

gitlab-compliance document gitstrings -i .gitlab-ci.yml --include-nested -o GITLAB-DOCS.md

Limit nesting with --max-include-depth (omit for unlimited). Depth 0 is the root file passed as -i.

gitlab-compliance document gitstrings -i .gitlab-ci.yml \
  --include-nested --max-include-depth 2 -o GITLAB-DOCS.md

Path-based render and sensitive values¶

Use dot paths on @render to control exactly which YAML subtree becomes a table. Parent segments work too (variables, megalinter.variables). Job names match case-insensitively when resolving paths against a full .gitlab-ci.yml.

Use @sensitive with a path to the value leaf (often ending in .value or .default) so the row is still documented but the cell is masked.

# @title Megalinter mode (masked)
# @render megalinter.variables.mode
# @sensitive megalinter.variables.mode.value
variables:
  APPLICATION: my-app

When -i is a CI YAML file, paths resolve against the entire pipeline file, not only the annotated fragment.

Output behavior¶

Generated fragments are rendered as markdown pipe tables (variables, inputs, jobs, and path-based slices). Multi-line or list values use <br> inside table cells rather than bullet lists.

• Only the gitstrings marker block on each target file is replaced.
• Default output file: -o / --output / --output-file, or -i when omitted (for CI YAML, README.md beside the file).
• When -o is set, every fragment writes to that file and # @output is ignored.
• Without -o, per-fragment # @output overrides the default for that snippet only.
• --keep-source (default): collapsible <details> with source YAML inside the marker block.
• Safe to run on the same README as generate; each command updates its own marker pair.

CI example¶

doc:gitstrings:
  image: python:3.12
  stage: test
  script:
    - pip install gitlab-compliance
    - gitlab-compliance document gitstrings -i README.md

See GitLab CI/CD for broader pipeline integration.

Troubleshooting¶