4 Minuten Lesezeit (762 Worte)

Dokumentenlenkung mit Git

Dienstag, 19. März 2024

Die Umsetzung einer ISO-27001-Zertifizierung fordert eine wirksame Dokumentenlenkung. Hierzu gehört beispielsweise, alte Versionen eines Dokumentes für die Nachvollziehbarkeit auffinden zu können und neue Dokumentenversionen vor Freigabe und Veröffentlichung des Dokuments zu genehmigen. Wie wäre es, eine solche Dokumentenlenkung mit einer Sourcecode-Versionierung wie git und GitLab umzusetzen?

Motivation

Die Dokumentenlenkung hat viele Anforderungen: Eine Versionshistorie, eine Markierung von Entwürfen und ein Genehmigungsprozess sollten gewährleistet sein. Git ist dafür ein gutes Tool, bringt es doch von Haus aus eine Versionierung mit, in der Änderungsentwürfe in Branches nebeneinander existieren können. Nimmt man sich die aus der Softwareentwicklung bekannten Merge Requests hinzu, hat man auch einen Genehmigungsprozess, in dem mehrere Reviewer Änderungen überprüfen, kommentieren und freigeben können. Alternativ wäre die klassische Vorgehensweise in Microsoft Word, Dokumente mit einer Versionshistorie im Dokumentenkopf und durchnummerierten Dateikopien zu verwenden; die durch den manuellen Aufwand für eine korrekte Versionierung wenig elegant ist.

Dateiformat

Zunächst einmal benötigen wir ein geeignetes Format für unsere Dokumente. Wir wählen hierfür Markdown, da es möglichst einfach zu lesen ist und gleichzeitig als Plain-Text-Format gut über Versionen hinweg mit einem Diff-Tool vergleichbar ist. Office-Dokumente hätten an dieser Stelle den Nachteil, einem Diff-Mechanismus nicht sehr zugänglich zu sein. Zudem lassen sich Markdown-Dokumente auch über den Webbrowser gut bearbeiten, ohne dass ein gesondertes Client-Tool notwendig wäre.

Dokumentenform

Für den Gebrauch in Dokumentenform sollte es weiterhin die Möglichkeit geben, die Dokumente als PDF weiterverteilen zu können. Hierfür wählen wir eine Kombination aus pandoc und LaTeX, um die Markdown-Dokumente in ein PDF zu übersetzen. Pandoc ist ein Konvertierungstool, das Dokumente zwischen verschiedenen Darstellungsformen umwandeln kann. Mit der Kommandozeilenoption „-s" (standalone) lässt sich ein vollständiges TeX-Dokument generieren, während mit „-o" (output) der entsprechende Dateiname eines Ausgabe-TeX-Dokumentes angegeben wird. Es ergeben sich für uns für die Generierung der Dokumentenform die folgenden Befehle, um die Markdown-Darstellung umzuwandeln:

pandoc -s -o policy.tex policy.md

latexmk -interaction=nonstopmode -pdf -xelatex policy.tex

Dokumentenkopf, Inhaltsverzeichnis und Versionsnummer

Um den Dokumenten noch einen geeigneten Header und ein Inhaltsverzeichnis zu geben, übernehmen wir das offizielle LaTeX-Template, das Pandoc nutzt, um ein Standalone-TeX-Dokument bereitzustellen und passen dieses an. Zugleich möchten wir die Revisionsnummer aus dem Git auf der PDF-Version anzeigen, um die aktuelle Version erkennen zu können. Die offizielle Quelle für das anzupassende Template ist das Github-Repository. Wir ändern es wie folgt:

\documentclass[]{scrartcl}
\usepackage{ordixpolicy}

\title{$title$~}
\author{$owner$~}
\documentVersion{$version$~}
…


\begin{document}

$test$

$for(include-before)$
$include-before$

$endfor$

\maketitlepage


\tableofcontents

\vspace{3cm}


$body$

$for(include-after)$
$include-after$

$endfor$
\end{document}

Der Aufruf, in dem wir nun die Git-Versionsnummer mit angeben, ändert sich damit zu:

pandoc --template template/default.latex --top-level-division=section
-M version=0123ffff -s -o policy.tex policy.md
latexmk -interaction=nonstopmode -pdf -xelatex policy.tex

Mit dem „--template”-Parameter übergeben wir das Template für das Standalone-TeX-Dokument, mittels der Option „--top-level-division” legen wir Sections als LaTeX-Überschriftenform fest und mit dem Parameter „-M" übergeben wir die Git-Versionsnummer als weitere Metadatenvariable.

Titel und Dokumenteneigentümer übernimmt pandoc aus dem YAML-Frontmatter, welches wir jedem Dokument voranstellen:

---
title: Leitlinie der ORDIX AG
author: "Vorstand"
approver: "ISB,QMB,DSK"
---
# Erste Überschrift

Hier beginnt der Text des Dokuments.

Automatisierung

Wir legen die Dokumente nun in ein git-Repository, in dem mehrere Dokumente Platz finden. Um alle Dokumente automatisch zu bauen, kommt nun ein kurzes Python-Script „convert.py” zum Einsatz, das Pandoc und LaTeX für alle Markdown-Dokumente jeweils auslöst und die PDF-Dokumente in einem Output-Verzeichnis baut. Wir legen es in die oberste Ebene des Repos:

from pathlib import Path
import os
import subprocess
import logging

log = logging.getLogger(__name__)

def run():
    cwd = Path(“.”).absolute()
    gitversion = subprocess.run([“git”,”rev-parse”,”—short”,”HEAD”],check=True,capture_output=True).stdout.decode().strip()
    output = Path(“./output”).absolute()
    output.mkdir(exist_ok=True)
    log.debug(“Output dir: %r”, output)
    input_files = list(Path(“.”).glob(“**/*.md”))
    for md_file in input_files:
        out_file_path = output / md_file.with_suffix(“.tex”)
        out_file_path.parent.mkdir(exist_ok=True,parents=True)
        tex_file = out_file_path
        log.info(“Converting %r”, md_file)
        inputs=cwd/”template”
        inputs=”.:”+str(inputs.absolute())+”:”
        os.putenv(“TEXINPUTS”,inputs)
        cmd = [“pandoc”,
               “—template”, “template/default.latex”, “—top-level-division=section”, “-s”,
               “-M”, “version=” + gitversion,
               “-o”, tex_file, md_file]
        log.debug(“Running %r”, cmd)
        subprocess.run(cmd, check=True)
        log.debug(“Chdir to %r”, tex_file.parent)
        try:
            os.chdir(tex_file.parent)
            cmd = [“latexmk”, “-interaction=nonstopmode”, “-pdf”, “-xelatex”, tex_file.absolute()]
            log.debug(“Running %r”, cmd)
            subprocess.run(cmd)
        finally:
            os.chdir(cwd)


if __name__ == ‘__main__’:
    logging.basicConfig(level=logging.DEBUG)
    run()

Continuous Integration

Dieses Python-Script lässt sich nun per Continuous-Integration-Tool automatisch ausführen. In unserem Fall verwenden wir Gitlab-CI und installieren im Docker-Image der texlive-Distribution das Tool pandoc nach, bevor wir unser Python-Script aufrufen. Die resultierenden PDF-Dateien archivieren wir als Artefakte. Die folgende YAML-Datei kann dafür als „.gitlab-ci.yml” in das Repo abgelegt werden:

variables :
  LATEX_IMAGE: texlive/texlive:latest

build:
  stage: build
  image: $LATEX_IMAGE
  script:
    - apt update 
    - apt install -y pandoc
    - python3 convert.py

  artifacts:
    paths:
      - "output/**/*.pdf"

Fazit

Mit den hier vorgestellten Tools ist es möglich, Dokumente in einem git-Repository zu lenken und daraus automatisch ansprechende PDF-Dokumente zu generieren. So lassen sich auch die Anforderungen der ISO 27001 an die Dokumentenlenkung einfach erfüllen.