AsciiDoc in einer Gitlab CICD-Pipeline bauen

Mit der .gitlab-ci.yml aus [sourcec] lassen sich Jobs konfigurieren, die AsciiDoc u.a. nach HTML und PDF konvertieren. Die Jobs werden nur getriggert, wenn sich .adoc-Dateien ändern, die Pipeline kann failen und die Artefakte werden für 1h unter dem Verzeichnis Output amgelegt. Für die Konvertierung wird der offizielle AsciiDoctor-Container genutzt. Asciidoctor selbst erhält dann einige Optionen übergeben.

Die Jobs erfüllen folgende Zwecke:

  • adoc2pdf: es werden PDFs und DOCX erzeugt und zusätzlich wird Kroki über den Kroki-Container eingebunden um Diagramme zu rendern und direkt in die PDF einzubinden. Zu Beginn wird ein Symlink auf das include-Verzeichnis angelegt, da AsciiDoctor im Container sonst mit den Includes failed.

  • krokibilder: Nutzt den Kroki- und Curl-Container um aus PUML-Dateien PlantUML-Diagramme als SVG und PNG zu erzeugen, falls man ein Diagramm alleinstehend als Bild benötigt.

stages:
  - build
  - download



###############################################################################
### clear ; git add .gitlab-ci.yml ; git commit -m `jetzt` ; git push ; jetzt
###############################################################################
###############################################################################
#
### handgeknüpfter AsciiDoctor-PDF; <SchumaSte> 2024-06-14
#
BHBtest:
################################ die nächsten beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  rules:
    - when: manual
  tags:
    - phoenix-tdc-qs
################################ die vorherigen beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  variables:
    CI_DEBUG_TRACE: "false"   ### Extra Debugging-Info in der Pipeline
    EXCLUDE_PATH: >
                -not -path "*/include/*"
                -not -path "*dOZ1_SicherheitsbewertungFLOSSQuellen*"
                -not -path "*/Team_Architektur/howto/*"
    VORLAGEN_DIR: ${CI_PROJECT_DIR}/Team_Architektur/asciidoc_templates
    BIBFILE: ${VORLAGEN_DIR}/phoenixbibliographie.bib
    ASCIIDOCHTML_CMD: >
         asciidoctor --backend xhtml5
            -r asciidoctor-lists
            -r asciidoctor-kroki
            -r asciidoctor-bibtex -a bibtex-style=apa  -a allow-uri-read -a data-uri -a kroki-server-url=http://krokiserver:8000
            -a pdf-style=${VORLAGEN_DIR}/include/DP_Architektur.yml
            -a bibtex-file=$BIBFILE
    ASCIIDOC_CMD: >
         asciidoctor-pdf
                        -r asciidoctor-lists
                        -r asciidoctor-bibtex
                            -a bibtex-style=apa
                            -a pdf-style=${VORLAGEN_DIR}/include/DP_Architektur.yml
                            -a bibtex-file=$BIBFILE
                        -r asciidoctor-kroki
                            -a allow-uri-read
                            -a data-uri
                            -a kroki-server-url=http://krokiserver:8000
                        -a pdf-themesdir=${VORLAGEN_DIR}/include
                        -a pdf-theme=DP_Architektur.yml
  stage: build
  allow_failure: true
 # tags:
 #   - phoenix-tdc-qs
  services:
    - name: common-docker-container-remote.repo-ex.zcdi.dataport.de/yuzutech/kroki:0.24.1
      alias: krokiserver
  artifacts:
    name: "$CI_COMMIT_REF_NAME-$CI_JOB_NAME"
    expire_in: 48h
    untracked: true
    exclude:
      - "*.adoc"
      - "*.puml"
      - "*.plantuml"
  image:
    name: common-docker-container-remote.repo-ex.zcdi.dataport.de/ubuntu:22.04
  before_script: |+
    export http_proxy="http://10.65.117.35:3128"
    export https_proxy="http://10.65.117.35:3128"
    export no_proxy="krokiserver"
    export KROKI_SERVER="http://krokiserver:8000/"
    apt update -y
    apt install -y locales ruby-dev build-essential pandoc detox graphicsmagick curl
     gem install -N racc:1.7.2 asciidoctor:2.0.21 asciidoctor-bibliography:0.11.0 asciidoctor-bibtex:0.9.0 asciidoctor-kroki:0.9.1 asciidoctor-lists:1.0.9 asciidoctor-pdf:2.3.14 asciidoctor-rouge:0.4.0 csl-styles:2.0.1 css_parser:1.12.0 nokogiri:1.12.5 public_suffix:4.0.7 text-hyphen:1.5.0
    ### bereinige Dateinamen von Sonder- und Leerzeichen und Umlauten, schreibe Ergebnis in Logdatei, wenn DETOX-LOG.txt leer ist, ist alles OK
    detox -r * | tee DETOX-LOG.txt
    ### alle PNGs einmal mit mogrify nach PNG konvertieren um kaputte Bilder-Exporte aus Word zu fixen
    find ~+ -iname "*.png" -exec bash -c 'printf "%q" "{}" | xargs gm mogrify' \;
    cd $CI_PROJECT_DIR
  script: |+
    find . -type f \( -iname \*.plantuml -o -iname \*.puml \) -exec sh -c 'curl http://krokiserver:8000/plantuml/png --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).png" ' \; -exec sh -c 'curl http://krokiserver:8000/plantuml/svg --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).svg" ' \;
    find . -type f -name "*.dot" -exec sh -c 'curl http://krokiserver:8000/graphviz/png --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .dot).png" ' \; -exec sh -c 'curl http://krokiserver:8000/graphviz/svg --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).svg" ' \;
    ### find ./ -iname Richtlinie_Vorlage_Header.adoc -not -path "${VORLAGEN_DIR}" -exec sh -c 'cp ${VORLAGEN_DIR}/include/*   ` echo {} |sed  "s/Richtlinie_Vorlage_Header.adoc//"  `' \;
    ### nach lokalen ADOC-Vorlagen suchen und diese loggen
    find ./ -iname Richtlinie_Vorlage_Header.adoc -not -path "${VORLAGEN_DIR}"  -printf 'VORLAGE GEFUNDEN IN: %h/%f \n' > VORLAGEN.log
    cd $CI_PROJECT_DIR
      find ~+ -iname "BHBTEST.adoc" ${EXCLUDE_PATH} -exec bash -c 'echo $(dirname "{}")' \; | sort |uniq| grep -v "/include" | while read ADOC_PATH
      do
        ADOC_PATH=$(printf '%q' "$ADOC_PATH") ; COMPILE_SKRIPT=$ADOC_PATH"/compile.sh"
        if [[ -f "$COMPILE_SKRIPT" ]]    ### prüfen ob die Datei compile.sh existiert
          then
            cd $ADOC_PATH && sh $COMPILE_SKRIPT  ### falls ja, compile.sh ausführen
          else
            cd $ADOC_PATH  ### ansonsten in das Verzeichnis wechseln
            for ADOCFILE in *.adoc   ### durch alle ADOCs im Verzeichnis iterieren
              do
               # if  grep -q -i "^include::.*Richtlinie_Vorlage_Header.adoc" "$ADOCFILE"  ### prüfe ob die Vorlage in der ADOC inkludiert wird -> komplexes Dokument
              if  grep -q -i "^include::.*Richtlinie_Vorlage_Header.adoc\|^= ADR-[0-9][0-9][0-9][0-9][0-9]: " "$ADOCFILE"  ### prüfe ob die Vorlage in der ADOC inkludiert wird -> komplexes Dokument
                then
                  echo -e "\n +++++++++++++++++++++++++#"  >> $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt
                  readlink -f "$ADOCFILE"  >> $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt  ### Error-Log befüllen
                  ${ASCIIDOC_CMD} "$ADOCFILE"  |& tee -a $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt ### komplexer Asciidoctor-PDF Befehl
                  ${ASCIIDOCHTML_CMD} "$ADOCFILE" -o "$ADOCFILE".html   ### HTML erzeugen als Temp für DOCX
                  pandoc --resource-path=.:include --to=docx --highlight-style=espresso --output "$(basename "$ADOCFILE" .html).docx" "$ADOCFILE".html  ### mit pandoc aus HTML DOCX machen
                  #rm "$ADOCFILE".html ### Temp HTML entfernen
                else   ### ADOC-Datei bindet die Vorlage NICHT ein
                  if [ $(grep -l "^include::.*Richtlinie_Vorlage_Header.adoc" *.adoc | wc -l) -lt 1 ] || [ $(grep -i -c "^// COMPILEME" "$ADOCFILE") -gt 0 ]   ### es gibt KEINE ADOC-Datei im Verzeichnis, die die Vorlage einbindet ODER der Kommentar COMILEME ist explizit in der Datei gesetzt
                    then
                      echo -e "\n +++++++++++++++++++++++++%"  >> $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt
                      readlink -f "$ADOCFILE"  >> $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt
                      asciidoctor-pdf "$ADOCFILE" |& tee -a $CI_PROJECT_DIR/ERRORLOG-AsciiDoctor.txt ### einfacher Asciidoctor-PDF Befehl
                    else
                      : ### NOOP
                  fi
                fi  ### prüfe ob die Vorlage in der ADOC inkludiert wird -> komplexes Dokument
              done   ### FOR: durch alle ADOCs im Verzeichnis iterieren
        fi ### IF prüfen ob die Datei compile.sh existiert
      done ### find while do
  after_script:





###############################################################################
###############################################################################
###############################################################################
### triggert den runner und das shell_skript zum export!
runnerbibperl:
################################ die nächsten beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  rules:
    - when: always
################################ die vorherigen beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  stage: build
  tags:
    - dsecurerunner
  script:
    - echo ${CI_JOB_TOKEN}  ${YOUR_USERNAME}:${PERSONAL_ACCESS_TOKEN}
    - date >> date.runner
    - cd BibExport && bash 00run_bib2adoc.sh



###############################################################################
###############################################################################
###############################################################################

ArtefakteLoeschen:
################################ die nächsten beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  rules:
    - when: manual
################################ die vorherigen beiden Zeilen entfernen, dann läuft die Pipeline bei jedem git push
  tags:
    - dsecurerunner
  allow_failure: true
  stage: build
  script:
#                                                                  "https://git.dataport.de/api/v4/projects/$CI_PROJECT_ID/artifacts"'
    - 'curl --request DELETE --header "JOB-TOKEN: $CI_JOB_TOKEN"  "https://git.dataport.de/api/v4/projects/$CI_PROJECT_ID/artifacts"'
    #- 'curl --request DELETE --header "JOB-TOKEN: $CI_JOB_TOKEN"  "https://gitlab.example.com/api/v4/projects/1/artifacts"'

###############################################################################
### clear ; git add .gitlab-ci.yml ; git commit -m `jetzt` ; git push ; jetzt
###############################################################################
###############################################################################
#
### handgeknüpfter AsciiDoctor-PDF; <SchumaSte> 2024-03-14
#
TAG_adoc2pdf:
################################ Artefakte nur exportieren, wenn ein Tag gesetzt wird. D.h. nur Releases werden exportiert auf dSecure Server
  only:
    - tags
################################ Artefakte nur exportieren, wenn ein Tag gesetzt wird. D.h. nur Releases werden exportiert auf dSecure Server
  variables:
    EXCLUDE_PATH: >
                -not -path "*/include/*"
                -not -path "*dOZ1_SicherheitsbewertungFLOSSQuellen*"
                -not -iname "ADR-*.adoc"
    VORLAGEN_DIR: ${CI_PROJECT_DIR}/Team_Architektur/asciidoc_templates
    ASCIIDOC_CMD: >
         asciidoctor-pdf
                        --trace
                        -r asciidoctor-lists
                        -r asciidoctor-bibtex
                            -a pdf-style=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/include/DP_Architektur.yml
                            -a bibtex-file=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/phoenixbibliographie.bib
                        -r asciidoctor-kroki
                            -a allow-uri-read
                            -a data-uri
                            -a kroki-server-url=http://krokiserver:8000
                        -a pdf-themesdir=${VORLAGEN_DIR}/include
                        -a pdf-theme=DP_Architektur.yml
  stage: build
  allow_failure: true
  tags:
    - phoenix-tdc-qs
  services:
    - name: common-docker-container-remote.repo-ex.zcdi.dataport.de/yuzutech/kroki:latest
      alias: krokiserver
  artifacts:
    name: "$CI_COMMIT_REF_NAME-$CI_JOB_NAME"
    expire_in: 48h
    untracked: true
  image:
    name: common-docker-container-remote.repo-ex.zcdi.dataport.de/ubuntu:22.04
  before_script:
    - export http_proxy="http://10.65.117.35:3128"
    - export https_proxy="http://10.65.117.35:3128"
    - export no_proxy="krokiserver"
    - export KROKI_SERVER="http://krokiserver:8000/"
    -  "apt update -y"
    -  "DEBIAN_FRONTEND=noninteractive TZ=Etc/UTC apt install -y tzdata"
    -  "apt upgrade -y "
    -  "apt install -y locales ruby-dev build-essential pandoc detox graphicsmagick curl"
    #-  "echo https://${ANSIBLE_RUNNER_CLONE_USERNAME}:${ANSIBLE_RUNNER_CLONE_PASSWORD}@git.dataport.de > git-credentials"
    #-  "git config --global credential.helper 'store --file=git-credentials'"
    #-  "git clone --branch ${CI_COMMIT_BRANCH} https://git.dataport.de/phoenix/devops/arch/phoenixArchitektur.git"
    -  "gem install racc -v 1.7.2"
    -  "gem install asciidoctor -v 2.0.21"
    -  "gem install nokogiri -v 1.12.5"
    -  "gem install asciidoctor-kroki -v 0.9.1"
    -  "gem install asciidoctor -v 2.0.21"
    -  "gem install asciidoctor-kroki -v 0.7.0"
    -  "gem install public_suffix -v 4.0.7"
    -  "gem install css_parser -v 1.12.0"
    -  "gem install asciidoctor-pdf -v 2.3.14"
    -  "gem install asciidoctor-lists -v 1.0.9"
    -  "gem install asciidoctor-bibliography -v 0.11.0"
    -  "gem install asciidoctor-bibtex  -v 0.9.0"
    -  "gem install asciidoctor-rouge  -v 0.4.0 "
    - detox -r * | tee TEE.txt
    - find ~+ -iname "*.png" -exec bash -c 'printf "%q" "{}" | xargs gm mogrify' \;
  script:
    - find . -type f -name "*.plantuml" -exec sh -c 'curl http://krokiserver:8000/plantuml/png --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).png" ' \; -exec sh -c 'curl http://krokiserver:8000/plantuml/svg --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).svg" ' \;
    - find . -type f -name "*.puml" -exec sh -c 'curl http://krokiserver:8000/plantuml/png --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).png" ' \; -exec sh -c 'curl http://krokiserver:8000/plantuml/svg --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).svg" ' \;
    - find . -type f -name "*.dot" -exec sh -c 'curl http://krokiserver:8000/graphviz/png --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .dot).png" ' \; -exec sh -c 'curl http://krokiserver:8000/graphviz/svg --data-binary "@""{}"  > "$(dirname "{}")"/"$(basename "{}" .puml).svg" ' \;
    - find ~+ -iname "*.adoc" ${EXCLUDE_PATH} -exec bash -c
        'echo $(dirname "{}")' \; | sort |uniq| grep -v "/include" |
            while read ADOC_PATH;
            do ADOC_PATH=$(printf '%q' "$ADOC_PATH") ; COMPILE_SKRIPT=$ADOC_PATH"/compile.sh";
              if [[ -f "$COMPILE_SKRIPT" ]];
                then cd $ADOC_PATH && sh $COMPILE_SKRIPT ;
                else cd  $ADOC_PATH ;
                  for ADOCFILE in *.adoc;
                  do
                    echo "DATEI = ${ADOC_PATH}/${ADOCFILE}" ;
                    if grep -q -i "include..include/Richtlinie_Vorlage_Header.adoc\[\]" "$ADOCFILE" ;
                      then ${ASCIIDOC_CMD} "$ADOCFILE" ;
                      else asciidoctor-pdf "$ADOCFILE" ;
                    fi;
                  done;
              fi;
            done
    - find . -type f -not -path "*/include/*" -name "*.adoc" -exec asciidoctor --backend xhtml5 -r asciidoctor-lists -r asciidoctor-kroki -r asciidoctor-bibtex -a allow-uri-read -a data-uri -a kroki-server-url=http://krokiserver:8000 -a pdf-style=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/include/DP_Architektur.yml -a bibtex-file=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/phoenixbibliographie.bib "{}" \;
    - find . -type f -not -path "*/include/*" -name "*.adoc" -exec asciidoctor --backend docbook -r asciidoctor-lists -r asciidoctor-kroki -r asciidoctor-bibtex -a allow-uri-read -a data-uri -a kroki-server-url=http://krokiserver:8000 -a pdf-style=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/include/DP_Architektur.yml -a bibtex-file=$CI_PROJECT_DIR/Team_Architektur/asciidoc_templates/phoenixbibliographie.bib "{}" \;
    -  find . -type f -name "*.html" -exec ls -l "{}" \; -exec sh -c 'echo "PANPAN!! = $(dirname "{}") " ;  pandoc --verbose --resource-path=.:include:$(dirname "{}"):$(dirname "{}")/include --to=docx --highlight-style=espresso --output "$(dirname "{}")"/"$(basename "{}" .lmth).docx" "{}"   ' \;
    -  find . -type f -name "*.xml" -exec ls -l "{}" \; -exec sh -c 'echo "PANPAN!! = $(dirname "{}") " ;  pandoc --verbose --resource-path=.:include:$(dirname "{}"):$(dirname "{}")/include --from=docbook --to=docx --highlight-style=espresso --output "$(dirname "{}")"/"$(basename "{}" .lmx).docx" "{}"   ' \;
    -  find . -type f -name "*.xml" -exec rm "{}" \;
  after_script:
    - cat /etc/os-release


###############################################################################
###############################################################################
###############################################################################
### Artefakte-Export auf den dSecure-Server, nur beim Erstellen eines TAGs, d.h. Release getriggert; <SchumaSte> 2024-03-14
TAG_runner_artifacts:
  stage: download
  needs:
    - job: TAG_adoc2pdf
      artifacts: true
  artifacts:
    untracked: true
################################ Artefakte nur exportieren, wenn ein Tag gesetzt wird. D.h. nur Releases werden exportiert auf dSecure Server
  only:
    - tags
################################ Artefakte nur exportieren, wenn ein Tag gesetzt wird. D.h. nur Releases werden exportiert auf dSecure Server
  tags:
    - dsecurerunner
  before_script:
    - mkdir -p /home/gitlab-runner/gitartifacts/attic
    - ls -l /home/gitlab-runner/gitartifacts/
  script:
    - 'curl -k -x "http://10.65.117.35:3128"  --location --output /home/gitlab-runner/gitartifacts/artifacts_$CI_COMMIT_TAG.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://git.dataport.de/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=runner_artifacts"'
  after_script:
    #- cp /home/gitlab-runner/gitartifacts/artifacts_$CI_COMMIT_TAG.zip  /home/gitlab-runner/gitartifacts/artifacts_$CI_COMMIT_TAG.zip-`date +%Y%m%d%H%M`.zip
    - mkdir -p /home/gitlab-runner/public_html/Artifacts/$CI_PROJECT_NAME/$CI_COMMIT_TAG
    - cp /home/gitlab-runner/gitartifacts/artifacts_$CI_COMMIT_TAG.zip /home/gitlab-runner/public_html/Artifacts/$CI_PROJECT_NAME/$CI_COMMIT_TAG/
    - cd /home/gitlab-runner/public_html/Artifacts/$CI_PROJECT_NAME/$CI_COMMIT_TAG/
    - unzip artifacts_$CI_COMMIT_TAG.zip
    - mv artifacts_$CI_COMMIT_TAG.zip ../
adoc2pdf:
  variables:
    EXCLUDE_PATH: > (1)
                -not -path "*/include/*"
                -not -path "*dOZ1_SicherheitsbewertungFLOSSQuellen*"
                -not -iname "ADR-*.adoc"
    VORLAGEN_DIR: ${CI_PROJECT_DIR}/Team_Architektur/asciidoc_templates (2)
    ASCIIDOC_CMD: > (3)
         asciidoctor-pdf
                        -r asciidoctor-kroki
                           -a allow-uri-read
                        -r asciidoctor-bibtex
                           -a bibtex-file=${VORLAGEN_DIR}/phoenixbibliographie.bib
                        -a pdf-themesdir=${VORLAGEN_DIR}/include
                        -a pdf-theme=DP_Architektur.yml
  stage: build
  allow_failure: true
  tags:
    - generic
  services:
    - name: common-docker-container-remote.repo-ex.zcdi.dataport.de/yuzutech/kroki:latest
      alias: krokiserver
  artifacts:
    expire_in: 10h
    untracked: true
  image:
    name: common-docker-container-remote.repo-ex.zcdi.dataport.de/asciidoctor/docker-asciidoctor
    entrypoint: ["/bin/sh", "-c"]
script:
  - |
  find ~+ -iname '*.adoc' ${EXCLUDE_ADOC_PATH} (4)
	-exec sh -c 'echo $(dirname "{}")' \; | sort |uniq| grep -v "/include" | while read ADOC_PATH; (5)
		do ADOC_PATH=$(printf '%q' "$ADOC_PATH") ; (6)
		   COMPILE_SKRIPT=$ADOC_PATH"/compile.sh"; (7)
			if [[ -f "$COMPILE_SKRIPT" ]]; (8)
				then cd $ADOC_PATH && sh $COMPILE_SKRIPT ; (9)
				else cd $ADOC_PATH ; (10)
					for ADOCFILE in *.adoc; (11)
					do
						if grep -q -i "include..include/Richtlinie_Vorlage_Header.adoc\[\]" $ADOCFILE ; (12)
							then ${ASCIIDOC_CMD} $ADOCFILE ; (13)
							else
								 if ! grep -q -i "include..include/Richtlinie_Vorlage_Header.adoc\[\]" *.adoc ; (14)
									then asciidoctor-pdf "$ADOCFILE" ; (15)
								fi ;
						fi;
					done;
			fi;
		done
1 EXCLUDE_PATH: Pfade, die find(1) nicht nach AsciiDoc durchsuchen soll, z.B. die ADRs
2 VORLAGEN_DIR: Pfad zum Verzeichnis mit den AsciiDoc-Templates, ${CI_PROJECT_DIR} wird von Gitlab zum Projektpfad expandiert
3 ASCIIDOC_CMD: Die Befehlszeile für AsciiDoctor mit den vollen Optionen für Richtlinien et.al.
4 find(1) sucht nach *.adoc, liefert mit ~+ den vollen Pfad zurück und exkludiert die Pfade aus <1>
5 Subshell aufrufen, und mit dirname den Pfad zur gefunden .adoc liefern, mit sort|uniq Dubletten ausschließen, falls mehrere *.adoc in einem Verzeichnis liegen, mit grep die include-Verzeichnisse ausschließen, mit while-Schleife in ADOC_PATH einlesen
6 Mit printf den Pfadnamen in $ADOC_PATH gemäß Shell-Regeln escapen z.B. für Leerzeichen oder Klammern: (1 2) → \(1\ 2\)
7 COMPILE_SKRIPT enthält den vollen Pfad zur Datei compile.sh
8 prüfe ob die Datei compile.sh im Adoc-Verzeichnis existiert
9 Wenn compile.sh existiert: führe das Skript mittel sh aus
10 Wenn compile.sh nicht existiert: gehe in das Adoc-Verzeichnis
11 Iteriere in einer for-Schleife durch alle Adoc-Dateien
12 Prüfe mit grep(1) ob in der Adoc-Datei die Datei Richtlinie_Vorlage_Header.adoc\[\] inkludiert wird
13 wenn die Vorlage inkludiert wird, rufe den vollen Asciidoctor-PDF-Befehl aus ${ASCIIDOC_CMD} auf
14 Prüfen ob es keine ADOC im Verzeichnis gibt, die die Vorlage einliest. Falls es eine ADOC mit Vorlagen-Include gibt, wird nur diese kompiliert, alle anderen ADOC-Dateien werden nicht extra kompiliert, da diese in der Mantel-Datei inkludiert werden.
15 wenn die Vorlage nicht inkludiert wird, rufe den einfachen Asciidoctor-PDF-Befehl auf

Gitlab-Releases zur Freigabe von Dokumenten nutzen

Git bzw. Gitlab bietet die Möglichkeit Quellcode verteilt zu entwickeln. Diese Möglichkeiten nutzen wir auch für die Arbeitsweise in der Architektur.

Unser gesamter Dokumentenbestand wird im Gitlab bzw. Git vorgehalten. Wird ein neues Dokument erzeugt oder ein bestehendes überarbeitet, wird ein neuer Branch des Main-Branches erzeugt. In diesem Branch können mehrere Architekten das Dokument bearbeiten. Ist das Dokument für den internen Review durch mindestens einen weiteren Architekten fertig, wird ein Merge Request gestellt und der aktuelle Feature-Branch gegen Develop gemerged. Natürlich erst, nachdem mindestens ein weiterer Architekt das Dokument überprüft und den Merge freigegeben hat.

Einmal pro Woche wird im Gitlab ein Release erstellt. In dieses Release fließen alle Merges seit dem letzten Release ein. Die Artefakte des Releases (PDF-Dateien) werden an die Gruppenleitung zur Freigabe geschickt. Eventuelle Änderungen werden eingearbeitet und das Release wird in den Main-Branch gemerged. Der Main-Branch stellt daher immer den Zustand des letzten freigegebenen Releases dar.

Arbeiten mehrere Architekten an einem Dokument, können vom Feature-Branch weitere Feature-Branches erzeugt und gemerged werden, bspw. für ein internes Review durch einen Sicherheitsarchitekten.