\chapter{Empfehlungen für die Planung und Implementierung von CI/CD}
\label{mas}
Auch wenn ein \cicd System nach der Einführung als Gesamtkomplex vorliegt, ist es unumgänglich, sich bei der Einführung auf die Detailebene des Use Cases als auch der Tools zu begeben. Nur so besteht die Chance, später im Betrieb des Systems die Vorteile von CI/CD nutzen zu können.

\todo{Aufschlüsseln der Rolle von Automatisierungs teams und Entwickler benzüglich Doku}
Während das Automatisierungsteam sehr viel umfangreichere Detailkenntnisse besitzen wird, muss der Softwareentwickler nur das für ihn relevanten Wissen in Form von Dokumentation vorliegen haben.

Im Folgenden werden Empfehlungen aufgezeigt, welche das Auftreten der
oben geschilderten Probleme verhindern können.

Die dargestellten Maßnahmen beziehen sich auf die Planung und Implementierung
eines \cicd Systems, Dokumentation und auch konkrete technische
Maßnahmen.

\section{Planung eines CI/CD Systems}
\label{mas:m1}

Die Einführung eines \cicd Systems beinhaltet nicht nur eine einfache
Automatisierung bestehender Prozesse, es handelt sich um eine komplexe
Automatisierung mit einem hohen Grad an Integration. Aus diesem Grund
stellt die sorgfältige Planung des Systems die Basis für eine
erfolgreiche Einführung von \cicd. Hierbei müssen Fragen zu den
Anforderungen und dem Design beantwortet werden.

\subsection{Frage nach dem Umfang der Automatisierung und den Objekten der Automatisierung}\label{mas:m1.1}

Entsprechend des individuell vorliegenden Entwicklungsprozesses werden die
Teilprozesse und ihre Abfolge definiert, welche das \cicd System
abbilden soll.

Typische Prozesse hierfür sind der

\begin{description}
    \item[Build-Prozess:] 
    Compile, ggf, Multimudulcompiling und Containerbau
    \item[Testprozess:]
    Modul, Integrations- und Systemtest
    \item[Analyseprozess:] 
    statisch oder dynamische Codeanalyse, Dependencyanalyse, Lizenzscan, Containersicherheitsanalyse
    \item[Delivery oder Deployment]
\end{description}

Die detaillierte Definition der \textbf{Inputschnittstelle} für das
\cicd System (z.B. Webhooks oder Dateiformate) muss ebenfalls erstellt werden. Dazu gehört
das Format, die Art, der Ort (Übergabeordner oder Repository) und der
Kontext (z.B. Release-Erstellung oder Snapshot-Version) unter dem das
\cicd System aufgerufen wird.

Zu diesem Zeitpunkt ist es notwendig, die \textbf{Rahmenbedingungen} für
das \cicd -- System festzulegen. Dazu gehören alle Arten von
unternehmens- oder projektspezifischen Konventionen und Richtlinien
beispielsweise zu Security, Code oder Systemarchitektur. Auch die
vorliegende Hardware könnte als Rahmenbedingung vorgegeben sein.

Für jeden \textbf{Prozessschritt} muss eine \textbf{detaillierte
funktionale Anforderung} erfolgen. Beispielsweise könnte für den
Analyseprozess die Arten von Checks festgelegt werden, wie der Check auf
bestimmte Designpatterns, Variablennamen oder allgemein gegen vorhandene
Regellisten.

~

Für den Prozessschritt des Delivery gilt es zu entscheiden, ob die
Softwareartefakte in einem einfachen Dateisystem bereitgestellt werden
oder in einem Artefakt-Managementsystem.

Wird das \cicd-System für ein bereits sich im
Softwareentwicklungsprozess vorliegendes Projekt eingeführt, ist die Planung einer
\textbf{Migration} notwendig. Hierbei müssen alle zu migrierende
Artefakte zu den entsprechenden Prozessschritten bestimmt und
beschrieben werden.

\subsection{Definition der Zielumgebung für Artefakte oder Software}\label{mas:m1.2}

Eine relevante Vorgabe in der Planung eines \cicd-Systems ist die
Festlegung der Zielumgebung für Artefakte (für Delivery) und im Falle
des Deployments die Zielumgebung für die Software.

Die Laufzeitumgebung der produktiven Software variiert in Abhängigkeit
des Use Case: Beispielsweise kann es sich um ein Autoradio, eine
Cloudumgebung, eine App, eine Website, einen Großrechner oder einen
Cluster handeln, welche lokal vorliegt oder ausschließlich über ein Netzwerk
zugänglich ist.

\subsection{Design des CI/CD Systems}\label{mas:m1.3}

\subsubsection{Toolauswahl}\label{mas:m1.3.1}

In diesem Planungsschritt gilt es, aus den Vorgaben über den Umfang,
Inhalt und die Zielumgebung des Use Case die \textbf{Wahl der
Toolkonfiguration} und auch die Entscheidung zwischen
\textbf{individueller Lösung} oder einer \textbf{All-in-One Lösung} zu
treffen.

Zunächst sollte eine Toolübersicht über Einzel- als auch All-in-One Tools,
mit einer genauen Analyse über Funktionalität und Schnittstellen
erstellt werden.

Ein systematischer Abgleich der Anforderungen aus \ref{mas:m1.1} und \ref{mas:m1.2} gegen
die Tooleigenschaften liefert eine potenzielle Toolauswahl, welche gegen
die Detailanforderungen und Rahmenbedingungen überprüft wird.

Dabei geht es um die Bestimmung der grundlegenden Realisierbarkeit und
auch um den Änderungsaufwand im Falle von Konflikten.

In die Entscheidung der Konfiguration fließen neben der funktionalen
Betrachtung auch der Entwicklungsaufwand für Einführung und Migration,
Lizenzkosten, Hardwarekosten und Training ein. Weitere betriebsbedingte
Aufwände beispielsweise für das Automatisierungsteam gehören auch zu dieser
Betrachtung.

Für den Fall, dass Tools und Systeme zu einer individuellen Lösung konfiguriert
werden, ist eine Integrationsanalyse notwendig.

\subsubsection{Design im Toolkontext}\label{mas:m1.3.2}

Nach der Toolentscheidung erfolgt die Detailplanung des Designs für die
getroffene Toolauswahl.

Hierzu gehört das Design der Toolintegration, die Migration, aber auch
das Design von möglichen technischen Maßnahmen wie in \ref{mas:m3}
dargestellt.

\subsection{Festlegung der Hardware für das CI/CD System}\label{mas:m1.4}

Die Art und Häufigkeit der Anfragen an das \cicd System
ist ebenfalls vom Use Case vorgegeben und bestimmt die Ausstattung der
Hardware mit CPU und RAM.

So hat eine pure Webanwendung mit einer CI Anfrage pro Stunde keine
besondere Anforderung an die eine Hardware, während ein CI-System,
welches 25 CI Anfragen in der Stunde erhält und für die Entwicklung von
CPU-oder sogar GPU intensiven Anwendungen gedacht ist, eine viel
stärkere Hardware mit höheren Taktraten und Kernen benötigt.

Solche hardwareintensiven Anwendungen finden sich häufig unter Machine
Learning Anwendungen und auch bei Quarkus- Native-Compiles.

Der Speicherbedarf muss ermittelt werden, entsprechend des
Speicherkonzepts und passend zu den gewählten Tools. Auch die Vorgaben
zur Spiegelung für die redundante Verwaltung der Datenserver können bei
der Konfigurationsentscheidung eine Rolle spielen, sowie Konventionen
aus dem Unternehmens- und Projektumfeld.

\section{Dokumentation}\label{mas:m2}

Ein \cicd System wird zum zentralen Element des
Softwareentwicklungsprozesses. Die starke Integration und Komplexität
erfordert eine umfangreiche Dokumentation für Entwickler als auch für
das Automatisierungsteam.

Die Dokumentation stellt für den Entwickler Informationen bereit, welche
ihm Kenntnisse zu den In- und Output-Schnittstellen vermittelt. Er muss
für sein individuelles Projekt Information darüber haben, wie und welche
Schritte durchlaufen werden und wie die Inputschnittstellen diesen
Ablauf durch die Pipeline beeinflussen können.

~

Das Automatisierungsteam benötigt Informationen über sowohl die \cicd Engine, eingesetzte
Tools und deren Interfaces als auch über die aktuelle Konfiguration der Systeme.

Bei Störungen im \cicd System kann diese Dokumentation helfen, das
System wiederherzustellen bzw. sogar extern als Workaround zu betreiben
(durch den Einsatz von Skripten zum Aufruf der einzelnen \cicd Schritte).

~

Im Anhang befindet sich das Bespiel einer Entwicklerdokumentation für die \cicd Implementierung eines Softwareentwicklungsprojektes. 
Die Dokumentation gehört zu einem Projekt, welches einen einfachen Java-Webservice durch \cicd automatisch integriert und ausliefert.
\todo{ref zu doku}

\section{technische Maßnahmen}\label{mas:m3}

\subsection{Lösungsansätze zur Umsetzung der Maßnahmen}\label{mas:m3.1}

Bei der Einführung eines \cicd System können mit Hilfe von technischen
Maßnahmen einige Probleme\todo{Synonym} vermieden werden, welche durch fehlendes Know-How der
Entwickler über die Funktionsweise des Systems verursacht werden.
Zusätzlich können technische Maßnahmen auch für die Einhaltung von
Richtlinien genutzt werden.

~

\setlength{\leftskip}{3em}
Beispielsweise kann durch technische Maßnahme verhindert werden, dass
eine ungetestete Softwareversion in einer Produktionsumgebung ungewollt
verwendet wird: Mit Hilfe eines Artefakt-Archivierungssystems können
passende Einstellungen vorgenommen werden, welche gewährleisten, dass
nur getestete Softwareversionen in die Produktion übertragen werden.
\emph{(\ref{B06} \nameref{B06})}

~

Weitere Beispiele sind die Verhinderung einer ungewollten Ausführung
eines Releases \emph{(\ref{B04} B04 -- ungewolltes Aktivieren der Pipeline durch
unbewusste Nutzung des Masterbranch),} deren Umsetzung im
Anschlusskapitel an einer konkreten Systemumgebung aufgezeigt wird.

~

Auch im \textbf{Speichermanagement} gibt es Möglichkeiten, den \emph{in
(\ref{B02} B02 - erschöpfte Speicherkapazität des CI/CD System)} beschriebenen
Speicherengpass zu verhindern: Durch ein \emph{geeignetes
\textbf{Lifecycle-Management}} könnten gewisse Artefakte nach einiger
Zeit gelöscht werden.

~

Weitere Maßnahmen könnten die Einführung einer \textbf{Hardwarequote} sein, um
eine ungewollte Hardwarebeanspruchung für einzelne Nutzer
vorzubeugen.

~

Das \textbf{vier-Augenprinzip} klingt zunächst nach einer \todo{rewrite}
organisatorischen Maßnahme und kann für unterschiedliche Prozessschritte
als Qualitätssicherungsmaßnahme vorgesehen werden. Die technische
Komponente dieser Maßnahme wäre die Dokumentation und
Ausführungsbestätigung dieser Schritte, welche als Voraussetzung für die
Fortsetzung des spezifischen Entwicklungsprozesses implementiert wird.

\setlength{\leftskip}{0pt}

~

\subsection{Beispiel für die Umsetzung von Maßnahmen zur Vermeidung
von B04 -- ungewolltes Aktivieren der Pipeline durch unbewusste Nutzung
des Masterbranch}

Die in B04 dargestellte Problemstellung besteht nicht nur aus der
versehentlichen Nutzung des Masterbranchs als Featurebranch. Die Brisanz
entsteht durch die Folgen bei der Ausführung der Push-Operation im \cicd
Umfeld. Der Build-Prozess wird gestartet und endet mit dem Deployment in
der produktiven Umgebung.

~

Das Szenario wird mit Hilfe einer einfachen \cicd Umgebung dargestellt.
Sie besteht aus einer kleinen Pipeline, welche die Funktionen Build und
Deploy abdeckt.

Das Branchpattern besteht aus einem Master-, Develop- und Featurebranch.

\subsubsection{Anforderungen für Branchmanagement/Deployment}

Im Folgenden werden die Anforderungen definiert, welche mit Hilfe der
\cicd Tools oder die \scm umgesetzt werden müssen.

~

Die erste Überlegung wäre, gleich zu dem Zeitpunkt, an dem der
Entwickler seine „versehentliche`` Programmiertätigkeit auf dem
Masterbranch beginnt, eingreifen zu können. An dieser Stelle sind jedoch
die Optionen in den weit verbreiteten Tools nicht gegeben und die
Möglichkeiten zu intervenieren, können erst später ansetzen.

\begin{itemize}

    \item \textbf{Ziel ist es, dass Softwareänderungen nur über die Merge-Operation
    in den Masterbranch übertragen werden dürfen.}\todo{umformulieren}

    \item \textbf{Ein Release darf nur ausgeführt werden, nach dem die
    Softwareänderung von einer autorisierten Person über das
    Vieraugenprinzip eine Überprüfung durchlaufen hat.}
    
\end{itemize}




Diese Anforderungen stellen somit die Grundlage, dass kein Code durch das
unbewusste Arbeiten auf dem Masterbranch in Produktion gelangt.

Hieraus ergeben sich die folgenden Einzelanforderungen für technische
Maßnahmen:
\begin{itemize}
    \item Verhinderung der Push-Operation für Code auf den Masterbranch
    \item Code muss über die Merge-Operation auf den Masterbranch übertragen werden
    \item Bei der Merge-Operation auf dem Masterbranch muss der Vorgang einer
    Code- und/oder Testüberprüfung durch eine weitere berechtigte Person
    nach dem Vieraugenprinzip vor der Release-Ausführung bestätigt werden

\end{itemize}


Im betrachteten Problemfall würde der Entwickler zunächst unbemerkt auf
dem Masterbranch arbeiten. Er bestätigt seine Codeänderungen und würde
versuchen, sie mit der Push-Operation auf das Remote-Git-Repository
hochzuladen. In diesem Augenblick erhält er jetzt eine Fehlermeldung
aufgrund des Verbotes der Push-Operation. Desweitern verhindert der
Prüfschritt für das Vieraugenprinzip, dass der Entwickler ein Release
durch Merge ausführen kann.

\subsubsection{Umsetzung im Versionsmanagmenttool oder in den CI Tools}

Es gibt eine Vielzahl von \textit{Quellcodeverwaltungen}, welche in der Lage
sind, gewisse Operationen zu regulieren. Zum Beispiel das Verhindern
von Push-Operationen auf gewissen Branches.

~

\setlength{\leftskip}{3em}
\noindent Die \scm GitLab lässt sich so konfigurieren, dass
man auf dem Masterbranch die Push-Operation nicht nutzen darf. Beim
Auslösen des Push kann eine Fehlermeldung angezeigt werden.

~

Entsprechend können im GitLab die Einstellungen getroffen werden, dass
nur die Merge-Operation erlaubt ist.

~

Ebenfalls ist es möglich, in GitLab bei einer Merge-Operation einen
zusätzlichen Validierungsschritt zu implementieren, welcher nur von
Usern mit einer speziellen Berechtigung bestätigt werden kann. Dieser
Schritt stellt dann die Bestätigung der Vieraugenüberprüfung und
Release-Freigabe durch die entsprechend autorisierte Person dar.

~

\setlength{\leftskip}{0px}

Sind diese Möglichkeiten der Regulierung von Operationen mit dem
vorhandenen Versionshaltungstool nicht gegeben, gibt es noch die
Möglichkeit über das CI-Tool einzugreifen:

~

\setlength{\leftskip}{3em}
\noindent Ein CI-Tool kann bei der Aktivierung nicht nachvollziehen, ob sich die
Anfrage aus einem Push- oder Merge-Aufruf ergeben hat.

~

Aber es gibt die Möglichkeit der Überprüfung des letzten Commits aus dem
Versionshaltungstool.
Die eine vorgegebene Berechtigung des Users kann überprüft werden,
welche z.B. mit Hilfe von digitalen Signaturen umgesetzt werden könnte.

~

Diese Regel stellt sicher, dass die CI-Pipeline für ein Release
gestartet wird, wenn der letzte Commit durch eine berechtigte Person
durchgeführt wird.

\setlength{\leftskip}{0pt}

\subsubsection{Dokumentation zur Erläuterung der Funktionalität für den
Entwickler}

Auch in der Projektdokumentation sollte auf dieses Regelwerk hingewiesen
werden. Neben der Darstellung der Branchpattern sollten die vorhandenen
Branches mit den erlaubten Operationen aufgeführt sein.

Eine Übersicht der möglichen Fehlermeldungen mit dem Hinweis auf die
umgesetzten technischen Maßnahmen ergänzt die Beschreibung.

Mit dieser Darstellung zur konkreten Umsetzung der Maßnahme zur
Vermeidung der unbewussten Entwicklung auf dem Masterbranch wird dieses
Kapitel abgeschlossen.

Das Bespiel verdeutlicht, wie umfangreich sich die Möglichkeiten der technischen Maßnahmen entfalten,
sobald man die Ebene von realem Use Case und Toolumgebung betritt.
