From 75799e32fc5e2948fc180fadd7dcf55d3b7d1d66 Mon Sep 17 00:00:00 2001 From: Marcel Feix Date: Fri, 13 May 2022 14:41:02 +0200 Subject: [PATCH] Docs(*): Translate everything to english Correction of some paths --- .../templates/common/common-ci-variablen.adoc | 22 ++++--- .../templates/container/container-build.adoc | 29 ++++++--- .../container/container-publish.adoc | 2 +- .../templates/container/container-scan.adoc | 28 ++++----- .../tool-documentation-tool.adoc | 28 +++++++++ .../java/gradle/gradle-test-template.adoc | 2 +- .../java/maven/maven-build-template.adoc | 2 +- .../java/maven/maven-verify-template.adoc | 2 +- .../templates/npm/npm-build-template.adoc | 7 ++- .../npm/npm-dependencies-template.adoc | 9 ++- .../templates/npm/npm-lint-template.adoc | 7 ++- .../templates/npm/npm-test-template.adoc | 7 ++- .../releasing/set-version-template.adoc | 2 +- .../static-analysis/repo-cve-scan.adoc | 24 +++++--- .../templates/static-analysis/tool-sonar.adoc | 14 ++--- documentation/contribution.adoc | 30 ++++++--- documentation/document.adoc | 29 ++++++--- documentation/generalInformation.adoc | 61 ++++++++++++------- pipelines/java-maven.gitlab-ci.yml | 2 +- .../container/container-build.gitlab-ci.yml | 4 +- .../java/maven/maven-build.gitlab-ci.yml | 3 +- .../maven/maven-database-diff.gitlab-ci.yml | 1 + .../maven/maven-dependencies.gitlab-ci.yml | 1 + .../java/maven/maven-verify.gitlab-ci.yml | 5 +- templates/npm/npm-build.gitlab-ci.yml | 3 + templates/npm/npm-dependencies.gitlab-ci.yml | 5 ++ templates/npm/npm-lint.gitlab-ci.yml | 6 +- templates/npm/npm-test.gitlab-ci.yml | 4 +- .../repo-cve-scan-trivy.gitlab-ci.yml | 7 ++- 29 files changed, 234 insertions(+), 112 deletions(-) diff --git a/documentation/chapters/templates/common/common-ci-variablen.adoc b/documentation/chapters/templates/common/common-ci-variablen.adoc index 8973738..4ffeb92 100644 --- a/documentation/chapters/templates/common/common-ci-variablen.adoc +++ b/documentation/chapters/templates/common/common-ci-variablen.adoc @@ -5,19 +5,21 @@ [[Generel-Variablen]] == Generelle Variablen -Wir stellen von uns empfohlene CI-Variablen in `{gitlab-ci-file}` zur verfügung. -Diese werden von uns gepflegt und bekommen von verschiedenen Projekten Feedback. -Es ist möglich das File direkt einzubinden. -Bitte folgende Variablen in `.gitlab-ci.yaml` setzen +Getting the correct and best variables and configurations can be very hard. +Within the `{gitlab-ci-file}` file we provide common CI-Variablen. +These variables collect best practices from different projekts and the official Gitlab-CI documentation. +It is possible to include this file directly within your project. +Some of our Templates and Pipelines rely on the following variables. |=== |Name |Description -|MAVE_IMAGE| Das Image das benutzt werden soll für Jobs die Maven benötigen. -|NODE_IMAGE| Das Image das benutzt werden soll für Jobs die NPM benötigen -|MAVEN_OPTS| Generelle optionen um Maven zu verändern -|MAVEN_CLI_OPTS| Optionen um Maven beim Bauen zu verbessern. -|FRONTEND_DIR| Wenn das Projekt ein Frontend besitzt, muss der Pfad definiert werden, damit die NPM Templates, das die Files finden kann. -|BACKEND_DIR| Wenn das Projekt ein Backend besitzt, muss der Pfad definiert werden. So kann gradle/maven an der richtigen Stelle ausgeführt werden. +|MAVE_IMAGE| The container image that will be used in jobs using Maven. We provide a https://www.exxcellent.de/confluence/pages/viewpage.action?pageId=119212963[Maven Base] Image with the eXXcellent Certificate. +|NODE_IMAGE| The container image that will be used in jobs using NPM. +|MAVEN_OPTS| Generell options to change the Maven configurations. +|MAVEN_CLI_OPTS| Options to change the Maven configurations on build time. +|GRADLE_OPTS| Generell options to change the Gradle configurations. +|FRONTEND_DIR| Directory where the frontend code can be found. This is useful when the repository contains frontend and backend Code. +|BACKEND_DIR| Directory where the backend code can be found. This is useful when the repository contains frontend and backend Code. |=== ---- diff --git a/documentation/chapters/templates/container/container-build.adoc b/documentation/chapters/templates/container/container-build.adoc index 43ff119..d279c69 100644 --- a/documentation/chapters/templates/container/container-build.adoc +++ b/documentation/chapters/templates/container/container-build.adoc @@ -10,21 +10,34 @@ | .container-build-kaniko | Baut Container mit dem Kaniko |=== -Erlaubt es das einfache bauen von Container Images. -Die Images werden als Tar in den CI-Artifacten abgelegt damit es einfach an weitere Pipeline-Schritte übergeben werden kann. -Für das Veröffentlichen des Images ist das Template ContainerPublish[Container Publish] zuständig. +Allows the simple building of Container Images. +We use Kaniko because it is faster than Docker builds and has less security problems. +The generated image will be passed as a Tar-Artefact between stages. +This allows us to make forder manipulations and scan jobs on one container Image. + +The template <<_container_publish>> allows you to publish the build image to a registry .Variables |=== |Name |Description | Default Value -|CONTEXT_LOCATION | Der Context des Dockerfiles. Im Fall von Jib ist dies der Path wo Maven/Gradle ausgeführt wird. | $CI_PROJECT_DIR -| EXTRA_ARGS | Weitere Argumente die an das Tool geschickt werden soll | "" +|CONTEXT_LOCATION +| Defines the context of the container build. In case of jib this Path should point to the location of your Gradle/Maven projects. +| $CI_PROJECT_DIR -| Nur bei Kaniko |- |- -| DOCKERFILE_LOCATION | Pfad zum Dockerfile | $CI_PROJECT_DIR/Dockerfile +| EXTRA_ARGS +| Additional argument that will be passed to the used tool. +| "" -| REGISTRY_MIRROR | Welcher Mirror benutzt werden soll | Nexus von exxcellent +| Only with Kaniko |- |- + +| DOCKERFILE_LOCATION +| Path to the Dockerfile +| $CI_PROJECT_DIR/Dockerfile + +| REGISTRY_MIRROR +| Define the container Mirror that should be used +| exxcellent Nexus |=== .Container Build Templates diff --git a/documentation/chapters/templates/container/container-publish.adoc b/documentation/chapters/templates/container/container-publish.adoc index 32bf360..93db1cf 100644 --- a/documentation/chapters/templates/container/container-publish.adoc +++ b/documentation/chapters/templates/container/container-publish.adoc @@ -1,5 +1,5 @@ :sourcedir: ../../../../templates - +[#_container_publish] = Container Publish Moves a container from the filesystem to a remote repository. diff --git a/documentation/chapters/templates/container/container-scan.adoc b/documentation/chapters/templates/container/container-scan.adoc index a448496..761f19f 100644 --- a/documentation/chapters/templates/container/container-scan.adoc +++ b/documentation/chapters/templates/container/container-scan.adoc @@ -3,11 +3,11 @@ = Container CVE Scanner Uses Trivy to scan for CVE Problems within your Image. -Needs a build container on the path `image.tar`. Use one of the Container build templates for this. +Needs a build container on the path `image.tar`. +Use one of the Container build templates for this. ==== -NOTE: NPM -Trivy can not find CVE's within Frontend containes that do not have a dependencie-lock file. +NOTE: NPM Trivy can not find CVE's within Frontend containes that do not have a dependencie-lock file. This file should not be part of the Image. We provide an additional static CVE-Analyser-Template that can find these CVE's within your Repo. We also have the https://gitlab.exxcellent.de/gilden/ci/security-scanner/security-scanner[Security-Scanner] if you have more than one image to scan. @@ -16,22 +16,20 @@ We also have the https://gitlab.exxcellent.de/gilden/ci/security-scanner/securit .Variables |=== |Name |Description | Default Value -|EXITCODE_ON_HIGH -| Bestimmt den Exit code der ausgegeben werden soll, wenn ein CVE der als HIGH markiert wurde, gefunden werden konnte. -Wenn 0 benutzt wird, läuft die CI weiter. -Benutzte `allow_failure: true` damit die CI weiter läuft aber ein Failure angezeigt wird. -| - +|EXITCODE +| Define the exit code Trivy uses when finding a CVE of the High category. +When using 0 the CI will run not exit when finding CVEs +Please consider using `allow_failure: true` instead of 0. The CI will show you an error but not fail. +| 1 + +| TRIVY_EXTRA_ARGS +| Extra arguments to pass to Trivy +| Please see Template -|EXITCODE_ON_CRITICAL -| Bestimmt den Exit code der ausgegeben werden soll, wenn ein CVE der als CRITICAL markiert wurde, gefunden werden konnte. -Wenn 0 benutzt wird, läuft die CI weiter. -Benutzte `allow_failure: true` damit die CI weiter läuft aber ein Failure angezeigt wird. -| - -|GRADLE_CLI_OPTS | Zusätzliche CLI Opts für Gradle | "" |=== .container scan template -[source, yaml] +[source,yaml] ---- include::{sourcedir}container/container-scan.gitlab-ci.yml[] ---- \ No newline at end of file diff --git a/documentation/chapters/templates/documentation/tool-documentation-tool.adoc b/documentation/chapters/templates/documentation/tool-documentation-tool.adoc index ebcae36..f18abd2 100644 --- a/documentation/chapters/templates/documentation/tool-documentation-tool.adoc +++ b/documentation/chapters/templates/documentation/tool-documentation-tool.adoc @@ -5,6 +5,34 @@ The Dokumentation tool template. More details and Variables can be found here: https://gitlab.exxcellent.de/gilden/ci/exxcellent-documentation-tool[Gilde CI/CD: exxcellent-documentation-tool]. +The following variables have to be set and are not optional. + +//todo these Variables hav to describet. +.Variables +|=== +|Name |Description | Default Value + +| FILE_INPUT +| A triplet of the converted html name followed by the page id of the confluence page we should generate below followed by the title of the parent page. Also supports multiple files separated by pipes: ".html,,\|.html,," +| NO DEFAULT + +| CONFLUENCE_SPACE +| Space Key of the target space e.g. RANDI for the Research and Innovation space +| NO DEFAULT + +| CONFLUENCE_USER +| Username in Confluence +| NO DEFAULT SET IN SECRETS + +| CONFLUENCE_PASSWORD +| Password in Confluence +| NO DEFAULT SET IN SECRETS + +| OPTIONAL +| https://gitlab.exxcellent.de/gilden/ci/exxcellent-documentation-tool/-/blob/master/documentation/chapters/general-information.adoc#user-content-confluence[Read Here] for more information. +| - +|=== + .dokumentation-tool [source,yaml] ---- diff --git a/documentation/chapters/templates/java/gradle/gradle-test-template.adoc b/documentation/chapters/templates/java/gradle/gradle-test-template.adoc index 9408765..ec4b0e7 100644 --- a/documentation/chapters/templates/java/gradle/gradle-test-template.adoc +++ b/documentation/chapters/templates/java/gradle/gradle-test-template.adoc @@ -6,7 +6,7 @@ endif::[] = Gradle Database Diff -This templates starts `gradle test` and saves the results as Artifacts. +These templates starts `gradle test` and saves the results as Artifacts. When Junit Reports are generated they will be published as Artefacts within the Pipelines. You can get a detailed view when clicking on Tests. diff --git a/documentation/chapters/templates/java/maven/maven-build-template.adoc b/documentation/chapters/templates/java/maven/maven-build-template.adoc index 9050c74..7e2c299 100644 --- a/documentation/chapters/templates/java/maven/maven-build-template.adoc +++ b/documentation/chapters/templates/java/maven/maven-build-template.adoc @@ -2,7 +2,7 @@ = maven-build-template -Dieses Template baut die .jar Files und speichert die Ergebnisse als Artifact. +These Templates will build a .jar file with Maven and provides it as an Artifact .Variables |=== diff --git a/documentation/chapters/templates/java/maven/maven-verify-template.adoc b/documentation/chapters/templates/java/maven/maven-verify-template.adoc index 7b25536..75796bf 100644 --- a/documentation/chapters/templates/java/maven/maven-verify-template.adoc +++ b/documentation/chapters/templates/java/maven/maven-verify-template.adoc @@ -4,7 +4,7 @@ ifndef::imagesdir[] :imagesdir: ../../../../images/ endif::[] -= maven-verify-template += Maven verify template This templates starts `mvn verify` and saves the results as Artifacts. diff --git a/documentation/chapters/templates/npm/npm-build-template.adoc b/documentation/chapters/templates/npm/npm-build-template.adoc index d79abf0..4790f55 100644 --- a/documentation/chapters/templates/npm/npm-build-template.adoc +++ b/documentation/chapters/templates/npm/npm-build-template.adoc @@ -1,12 +1,15 @@ :sourcedir: ../../../../templates/ -= npm-build-template += NPM Build Template -Dieses Template baut das NPM projekt und speichert die Ergebnisse als Artifact. +This template will build a NPM project and saved the artifacts for the next build step. .Variables |=== |Name |Description | Default Value +|ADDITIONAL_GLOBAL_PACKAGES +| Additional packages that should be installed in the before script +| "" |=== .npm-build-template diff --git a/documentation/chapters/templates/npm/npm-dependencies-template.adoc b/documentation/chapters/templates/npm/npm-dependencies-template.adoc index 6689f4c..6218f10 100644 --- a/documentation/chapters/templates/npm/npm-dependencies-template.adoc +++ b/documentation/chapters/templates/npm/npm-dependencies-template.adoc @@ -1,13 +1,16 @@ :sourcedir: ../../../../templates/ -= npm-dependencies-template += NPM Dependencies template -Dieses Template läd die NPM Abhängigkeiten des Projekts runter. -Bitte den Cache hinzufügen. Siehe xref:Generel-Variablen[Generelle Variablen] +This template loads the NPM dependencies of the project. +Please add the NPM cache. Look xref:Generel-Variablen[generell Variables] .Variables |=== |Name |Description | Default Value +|ADDITIONAL_GLOBAL_PACKAGES +| Additional packages that should be installed in the before script +| "" |=== .npm-dependencies-template diff --git a/documentation/chapters/templates/npm/npm-lint-template.adoc b/documentation/chapters/templates/npm/npm-lint-template.adoc index 9d74a00..1ea7ebd 100644 --- a/documentation/chapters/templates/npm/npm-lint-template.adoc +++ b/documentation/chapters/templates/npm/npm-lint-template.adoc @@ -1,12 +1,15 @@ :sourcedir: ../../../../templates/ -= npm-lint-template += NPM Lint template -Dieses Template durchläuft den Linter des NPM Projekts. +This template starts the linter of your NPM project. .Variables |=== |Name |Description | Default Value +|ADDITIONAL_GLOBAL_PACKAGES +| Additional packages that should be installed in the before script +| "" |=== .npm-lint-template diff --git a/documentation/chapters/templates/npm/npm-test-template.adoc b/documentation/chapters/templates/npm/npm-test-template.adoc index 7a67dd8..8e61106 100644 --- a/documentation/chapters/templates/npm/npm-test-template.adoc +++ b/documentation/chapters/templates/npm/npm-test-template.adoc @@ -1,12 +1,15 @@ :sourcedir: ../../../../templates/ -= npm-test-template += NPM Test Template -Dieses Template baut das NPM Projekt. +This template will run your NPM unit tests .Variables |=== |Name |Description | Default Value +|ADDITIONAL_GLOBAL_PACKAGES +| Additional packages that should be installed in the before script +| "" |=== .npm-test-template diff --git a/documentation/chapters/templates/releasing/set-version-template.adoc b/documentation/chapters/templates/releasing/set-version-template.adoc index 8f68815..68f6b4b 100644 --- a/documentation/chapters/templates/releasing/set-version-template.adoc +++ b/documentation/chapters/templates/releasing/set-version-template.adoc @@ -1,7 +1,7 @@ :sourcedir: ../../../../templates/ -= set-version += Set Version This template provides the job for increasing the tag version. For more details look at https://gitlab.exxcellent.de/gilden/ci/exxcellent-increase-version-tool[Gilde CI/CD: exxcellent-increase-version-tool]. diff --git a/documentation/chapters/templates/static-analysis/repo-cve-scan.adoc b/documentation/chapters/templates/static-analysis/repo-cve-scan.adoc index 2b49111..211ec3a 100644 --- a/documentation/chapters/templates/static-analysis/repo-cve-scan.adoc +++ b/documentation/chapters/templates/static-analysis/repo-cve-scan.adoc @@ -1,30 +1,34 @@ :sourcedir: ../../../../templates/ -= Repo-CVE-Scan += Repo CVE Scan -Scanned die gesamte Repo mit Trivy auf CVEs und Konfigurationsproblemen in Deployment files. +This template uses Trivy to scan for CVEs, Configuration Problems and Secrets within your Repository. .Variables |=== |Name |Description | Default Value |EXITCODE -| Definiert den Exitcode der benutzt wird, wenn Trivy Probleme findet. -Bei 0 läuft die Pipeline durch, auch wenn Probleme gefunden werden. -Überlege, ob du die Flag `allow_failure: false` benutzen willst. +| Define the exit code Trivy uses when finding a CVE of the High category. +When using 0 the CI will run not exit when finding CVEs +Please consider using `allow_failure: true` instead of 0. The CI will show you an error but not fail. | 1 |TRIVY_EXTRA_ARGS -| Weitere Argumente die du an Trivy übergeben kannst. +| Extra arguments to pass to Trivy | --no-progress --ignore-unfixed --severity HIGH,CRITICAL -|SCAN_PATH -| Der Path ab dem Trivy die Repo scannen soll. -| Root der Repository +| TRIVY_CKECKS +| Allows you to configure what checks will be executed on your Repository +| "vuln,config,secret" + +| SCAN_PATH +| Path where Trivy should scan for security errors. +| $CI_PROJECT_DIR |=== .Repo CVE scan template -[source, yaml] +[source,yaml] ---- include::{sourcedir}static-analysis/repo-cve-scan-trivy.gitlab-ci.yml[] ---- \ No newline at end of file diff --git a/documentation/chapters/templates/static-analysis/tool-sonar.adoc b/documentation/chapters/templates/static-analysis/tool-sonar.adoc index 5f4ce24..445b9b9 100644 --- a/documentation/chapters/templates/static-analysis/tool-sonar.adoc +++ b/documentation/chapters/templates/static-analysis/tool-sonar.adoc @@ -1,18 +1,16 @@ :sourcedir: ../../../../templates/ = sonar-template -Ruft den Sonar Job für das Projekt auf. -Mehr Details zu finden hier: https://gitlab.exxcellent.de/gilden/ci/exxcellent-sonar-tool[Gilde CI/CD: exxcellent-sonar-tool]. +The following templates provide integrations for Sonar .Variables |=== |Name |Description | Default Value -|SONAR_HOST_URL | Die URL des eXXcellent sonar servers | http://sonar7.exxcellent.de/sonar7 -|SONAR_TOKEN | Token um geschützte Sonar Funktionen auszuführen | "" -|SONAR_PROJECT_KEY | Der Sonar-Projekt-Key. | "" -|SONAR_PROJECT_NAME | Der Sonar-Projekt-Name. | "" (Es wird dann standardmäßig der Maven project.name verwendet) -|SONAR_EXCLUSIONS | Von Sonar auszuschließende Bereiche | **/target/**,**/src/test/** -|GRADLE_CLI_OPTS | Zusätzliche CLI Opts für Gradle | "" +|SONAR_HOST_URL | The Url for the Sonar server | http://sonar7.exxcellent.de/sonar7 +|SONAR_TOKEN | The Sonar token to call protected sonar funtkions | "" +|SONAR_PROJECT_KEY | The Sonar-Projekt-Key of your Project. | "" +|SONAR_PROJECT_NAME | The Sonar-Projekt-Name. | "" (If you set project.name in maven the POM value will be used if this is empty) +|SONAR_EXCLUSIONS | Paths that will not be scanned by Sonar | **/target/**,**/src/test/** |=== diff --git a/documentation/contribution.adoc b/documentation/contribution.adoc index e342e38..fbd0d7a 100644 --- a/documentation/contribution.adoc +++ b/documentation/contribution.adoc @@ -2,19 +2,33 @@ :gitlab-ci-file: /common/common-ci-variablen.gitlab-ci.yml -Im Folgenden sind ein paar Regeln wie die Repo aufgebaut ist um ein möglicht einfaches einarbeiten und zusammenarbeiten zu ermöglichen. - +Please follow the these rules to provide excellent templates. +We found that these rules will lead to better and more usable templates. == Template Names convention -Template Namen fangen immer mit dem Prefix des Files an, in dem sie sich befinden. -Wenn in dem File mehrere Templates enthalten sind, wird an den Filenamen ein Suffix gehängt der, die Funktion des Templates zusammenfasst. -Das machen mir damit die CI Files und die Templates eine Verbindung zueinander haben. -Die Erfahrung hat gezeigt das es sonst schwer wird die Templates mit den Imports zu verbinden. +Template Names should begin with the Prefix of the file there are contained in. +If a Template File contains more than on template a Suffix should be provided. +This Suffix should describe the functionality of the Template as good as posible. + +This rules makes it easy to find the file within our repositories. If you only have a yml definition. +Our experience told us it can be hard to find the File a Template Job is in. ==== -Beispiel: +Example: -fuu.gitlab-ci.yml enthält template die anfangen mit .fuu-feature1 und .fuu-feature2 +The file `fuu.gitlab-ci.yml` contains the template that start with `.fuu*` +It could Container the Templates `.fuu-feature1` or `.fuu-feature2` ==== +== Mono Repo support + +We try to give as much Mono-Repo support as possible. +Because of this, the execution path of jobs should be variable. +Use a `cd $SOME_VAR_TO_PATH` within your `script` or `before_script` definitions. +The default path to should point to `$CI_PROJECT_DIR`. + +== Use of Before/After script + +avoid using `before_script` and `after_script` within a template. +these scripts should be overridable by the template user. diff --git a/documentation/document.adoc b/documentation/document.adoc index 0a3acce..6d4391a 100644 --- a/documentation/document.adoc +++ b/documentation/document.adoc @@ -19,9 +19,8 @@ endif::[] :classification: Intern :author: Marcel Feix -Diese Repository enthält alle generellen CI Templates der CI Gilde. -Templates für Tools werden in den Repositorys der Tools gepflegt. - +This Repository contains all CI Templates maintained by the CI-Gilde. +It also provides templates for simpler integration of CI-Gilde Tools. // ########################################################################### // Das Inhaltsverzeichnis ist nur im generierten HTML/PDF sichtbar (immer an erster Stelle, technisch bedingt) @@ -43,6 +42,9 @@ include::contribution.adoc[leveloffset=1] == Deployment - IaC +Our collection of Infrastructure as Code (IaC) Templates. +For Terraform Template please use the https://docs.gitlab.com/ee/user/infrastructure/iac/[official Templates] provided by Gitlab. + include::chapters/templates/IaC/ansible.adoc[leveloffset=2] include::chapters/templates/IaC/docker-compose.adoc[leveloffset=2] include::chapters/templates/IaC/ssh-transfer-data.adoc[leveloffset=2] @@ -50,6 +52,8 @@ include::chapters/templates/IaC/ssh-transfer-data.adoc[leveloffset=2] == Container Templates +Our collection of Container Templates. + include::chapters/templates/container/container-build.adoc[leveloffset=2] include::chapters/templates/container/container-publish.adoc[leveloffset=2] include::chapters/templates/container/container-scan.adoc[leveloffset=2] @@ -57,8 +61,8 @@ include::chapters/templates/container/container-scan.adoc[leveloffset=2] == Releasing Templates -Im folgende sind erweiterte Templates zu finden für das https://gitlab.exxcellent.de/gilden/ci/exxcellent-increase-version-tool[Increase-Version-Tool] der CI Gilde. -Für vorgegebene Release Pipelines bitte im Abschnitt <<_pipelines>> gucken. +The following Templates provide an simpler integration into the https://gitlab.exxcellent.de/gilden/ci/exxcellent-increase-version-tool[Increase-Version-Tool] of the CI-Gilde. +We also provide finished Pipelines in our <<_pipelines>> section. We highly recommend using those Pipelines since this is our reference Implementation. include::chapters/templates/releasing/push-tag-and-version-template.adoc[leveloffset=3] include::chapters/templates/releasing/set-version-template.adoc[leveloffset=3] @@ -68,6 +72,8 @@ include::chapters/templates/releasing/mail-template.adoc[leveloffset=3] == NPM Templates +Our collection of NPM Templates. + include::chapters/templates/npm/npm-dependencies-template.adoc[leveloffset=2] include::chapters/templates/npm/npm-build-template.adoc[leveloffset=2] include::chapters/templates/npm/npm-lint-template.adoc[leveloffset=2] @@ -75,14 +81,19 @@ include::chapters/templates/npm/npm-test-template.adoc[leveloffset=2] == Maven Templates +Our collection of Maven Templates. + include::chapters/templates/java/maven/maven-dependencies-template.adoc[leveloffset=2] include::chapters/templates/java/maven/maven-build-template.adoc[leveloffset=2] include::chapters/templates/java/maven/maven-verify-template.adoc[leveloffset=2] == Gradle Templates -Aktuell gehen wir davon das der Gradle Wrapper in dem Projekt vorhanden ist. -Sollte dieser noch nicht vorhanden sein kann er mit dem Befehl `gradle wrapper` erstellt werden. +Our collection of Gradle Templates. +Currently, we start our Templates from the Gradle Wrapper within your Projekt. +If you do not have a wrapper you can create on with the command `gradle wrapper`. +Please keep in mind updating the wrapper from time to time. +We recommend using https://www.exxcellent.de/confluence/x/S4WCC[Renovate] for this task. include::chapters/templates/java/gradle/gradle-build-template.adoc[leveloffset=2] include::chapters/templates/java/gradle/gradle-test-template.adoc[leveloffset=2] @@ -90,11 +101,15 @@ include::chapters/templates/java/gradle/gradle-db-diff-template.adoc[leveloffset == Static Analysis +With the following collection we provide Static code and Artefact analysis tools. + include::chapters/templates/static-analysis/repo-cve-scan.adoc[leveloffset=2] include::chapters/templates/static-analysis/tool-sonar.adoc[leveloffset=2] == Documentation +This collection provides templates to simplify your dokumentation prozess. + include::chapters/templates/documentation/tool-documentation-tool.adoc[leveloffset=2] [#_pipelines] diff --git a/documentation/generalInformation.adoc b/documentation/generalInformation.adoc index e9c3295..b8a5223 100644 --- a/documentation/generalInformation.adoc +++ b/documentation/generalInformation.adoc @@ -1,27 +1,40 @@ :sourcedir: ../../../../templates -== Templates und Pipelines +== Templates and Pipelines -In dieser Repository sind CI Templates und CI Pipeline-Templates zu finden. -Templates sind vorgefertigte Jobs, die jeweils einen Use-Case abbilden sollen und in dein Projekt importiert werden können. Die meisten Templates haben kein abhängigkeiten untereinander. Wenn doch, werden die Abhängigkeiten dokumentiert. -Alle Templates sind im Ordner Templates zu finden. +Within this Repository all CI Templates and CI Pipeline-Templates of the CI-Gilde can be found. +Templates are predefined Jobs. +These jobs implement one Use-Case as good as possible. +There mend to be imported to your project as simple as possible and provide best practises learned in multiple projects. +Most Templates do not have dependencies between Jobs. +If Jobs have dependencies the documentation will tell you how to integrate it. +Templates can be found in the Directory `Templates`. -Da eine CI jedoch aus Pipelines besteht und Gitlab die Möglichkeit Multi-Projekt- und Child-Pipelines zu benutzen, werden hier auch vorgefertigte Pipelines bereitgestellt. -Diese Pipeline-Templates bilden komplexere Use-Cases ab. -Pipelines sind in dem dafür vorgesehenen Pipeline Ordner zu finden. +We also provide finished Pipeline-Templates to integrate into your project. +Gitlab-CI has the possibility to execute Multi-Project- and Child-Pipelines that can be hard to integrate. +We have Pipline-Templates that implement common CI-Problems we found in different projekts. +These Piplines-Templates are not as Dynamic as templates but allow to integrate a lot of functionality within a short time. +Pipeline-Templates can be found in the Directory `Pipeline`. -== Wie können Templates benutzt werden +== How to use Templates? -Damit du die Templates in deinem Projekt zu benutzten kannst, musst du folgendes machen: +To use our Templates in your project you have to do the following: -1. `Include` das Template file das du benutzen willst in deinem `.gitlab-ci.yaml` File. -2. Jetzt kannst du in von dir gewählten Job das Template mit dem keyword `extend` als Ausgangspunkt benutzen. -3. Du kannst den Job für deinen Anwendungszweck weitere verändern indem du diese bei dir Überschreibst. +1. `Include` the Template file you want to use within your `.gitlab-ci.yaml` File. +2. Now you have access to the template within your CI file. +Use the keyword `extend` to extend on the imported Template. +3. Most of the time you also have to provide additional variables within you CI Configuration. +To change or override a functionality of the gitlab Template just configure your gitlab-ci Job normally. +Read more about the `extend` keyword https://docs.gitlab.com/ee/ci/yaml/yaml_optimization.html#use-extends-to-reuse-configuration-sections[here] ==== -Bei dem folgenden Beispiel wurde als ref der Tag 1.0.0 gesetzt. -Wir empfehlen diesen Tag zu setzen damit Änderungen von uns nicht eure CI Skripte kaputt machen. -Um automatisch mitzubekommen, wenn sich die CI verändert empfehlen wir das Benutzen von Renovate +The following example has the key `ref` set to the Tag `2.0.0`. +We recommend setting the `ref` to a Tag of the repository. +Changes on Master will not destroy your CI-Skripts. +To update this `ref` we recommend using Renovate. +You can also follow the Main branch of this repository. +We try not to break your stuff. +We are still learning a lot of stuff. ==== [source,yaml] @@ -31,22 +44,28 @@ stages: include: - project: 'gilden/ci/gitlab-ci-templates' - ref: '1.0.0' + ref: '2.0.0' file: - '/templates/java/maven/maven-verify.gitlab-ci.yml' test-image: stage: test-image extends: .maven-verify +#Example overriding Variable + variables: + GRADLE_CLI_OPTS: "$SOME_VARIABLE" +#Example overriding rules rules: - - if: $NURAUFMEINEMBRANCH + - if: $SOME_VARIABLE +#Example overriding scripts before_script: - - echo "meine änderungen" + - echo "my overriding changes" ---- -== Wie können Pipelines benutzt werden +== How to use Pipeline-Templates? -Um Pipelines zu benutzen, müssen diese nur mit `Include` importiert werden. -Für weitere Informationen ließ bitte die Doku der Pipelines selbst. +Most Pipelines Templates just have to be `included` within your CI File. +These have a high integration and are not really dynamic. +Please read the Dokumentation of every pipeline-template. diff --git a/pipelines/java-maven.gitlab-ci.yml b/pipelines/java-maven.gitlab-ci.yml index 1e7ca52..7e32e7f 100644 --- a/pipelines/java-maven.gitlab-ci.yml +++ b/pipelines/java-maven.gitlab-ci.yml @@ -8,7 +8,7 @@ include: # todo doc welche Variablen gesetzt werden müssen.before_script: # variables: -# SONAR_PROJECT_KEY: "gilde.ci.cd.restservice:java-backend-template" +# SONAR_PROJECT_KEY: "" Dependencies-Java: extends: .maven-dependencies diff --git a/templates/container/container-build.gitlab-ci.yml b/templates/container/container-build.gitlab-ci.yml index 33a776d..c5c5af0 100644 --- a/templates/container/container-build.gitlab-ci.yml +++ b/templates/container/container-build.gitlab-ci.yml @@ -11,7 +11,7 @@ extends: .container-build-common image: $MAVEN_IMAGE script: - - cd $CONTEXT_LOCATION + - "cd $CONTEXT_LOCATION" - mvn $MAVEN_CLI_OPTS jib:buildTar -DskipTests $EXTRA_ARGS .container-build-jib-gradle: @@ -20,7 +20,7 @@ variables: EXTRA_ARGS: $GRADLE_EXTRA_ARGS script: - - cd $CONTEXT_LOCATION + - "cd $CONTEXT_LOCATION" - ./gradlew $GRADLE_CLI_OPTS jibBuildTar -DskipTests $EXTRA_ARGS .container-build-kaniko: diff --git a/templates/java/maven/maven-build.gitlab-ci.yml b/templates/java/maven/maven-build.gitlab-ci.yml index 9cc43a2..764594e 100644 --- a/templates/java/maven/maven-build.gitlab-ci.yml +++ b/templates/java/maven/maven-build.gitlab-ci.yml @@ -2,6 +2,7 @@ stage: build image: $MAVEN_IMAGE before_script: + - "cd $BACKEND_DIR" - > if [ ! -z "$CI_COMMIT_TAG" ]; then mvn $MVN_EXTRA_ARGS $MAVEN_CLI_OPTS versions:set -DnewVersion=$CI_COMMIT_TAG -DgenerateBackupPoms=false @@ -12,4 +13,4 @@ expire_in: 2 weeks when: always paths: - - $BACKEND_DIR/target/*.jar + - "**/target/*.jar" diff --git a/templates/java/maven/maven-database-diff.gitlab-ci.yml b/templates/java/maven/maven-database-diff.gitlab-ci.yml index b6487ad..ade5154 100644 --- a/templates/java/maven/maven-database-diff.gitlab-ci.yml +++ b/templates/java/maven/maven-database-diff.gitlab-ci.yml @@ -9,4 +9,5 @@ include: MAVEN_EXTRA_OPTS: "" PATH_TO_DIFF: "target/db-diff.xml" script: + - "cd $BACKEND_DIR" - mvn compile liquibase:update liquibase:diff $MAVEN_EXTRA_OPTS diff --git a/templates/java/maven/maven-dependencies.gitlab-ci.yml b/templates/java/maven/maven-dependencies.gitlab-ci.yml index 3f938a4..5296dea 100644 --- a/templates/java/maven/maven-dependencies.gitlab-ci.yml +++ b/templates/java/maven/maven-dependencies.gitlab-ci.yml @@ -2,4 +2,5 @@ stage: dependencies image: $MAVEN_IMAGE script: + - "cd $BACKEND_DIR" - "mvn $MAVEN_CLI_OPTS dependency:resolve" \ No newline at end of file diff --git a/templates/java/maven/maven-verify.gitlab-ci.yml b/templates/java/maven/maven-verify.gitlab-ci.yml index 1208c67..6ecd5dc 100644 --- a/templates/java/maven/maven-verify.gitlab-ci.yml +++ b/templates/java/maven/maven-verify.gitlab-ci.yml @@ -2,11 +2,12 @@ image: $MAVEN_IMAGE stage: verify script: + - "cd $BACKEND_DIR" - mvn $MAVEN_CLI_OPTS verify artifacts: expire_in: 2 weeks reports: junit: - - target/surefire-reports/TEST-*.xml - - target/failsafe-reports/TEST-*.xml + - "**/target/surefire-reports/TEST-*.xml" + - "**/target/failsafe-reports/TEST-*.xml" diff --git a/templates/npm/npm-build.gitlab-ci.yml b/templates/npm/npm-build.gitlab-ci.yml index f0d9f17..905b357 100644 --- a/templates/npm/npm-build.gitlab-ci.yml +++ b/templates/npm/npm-build.gitlab-ci.yml @@ -1,7 +1,10 @@ .npm-build: image: $NODE_IMAGE stage: build + variables: + ADDITIONAL_GLOBAL_PACKAGES: "" before_script: + - npm install -g $ADDITIONAL_GLOBAL_PACKAGES #Todo this needs Testing!! - > if [ "$CI_COMMIT_TAG" != "" ]; then diff --git a/templates/npm/npm-dependencies.gitlab-ci.yml b/templates/npm/npm-dependencies.gitlab-ci.yml index 0980d89..758313d 100644 --- a/templates/npm/npm-dependencies.gitlab-ci.yml +++ b/templates/npm/npm-dependencies.gitlab-ci.yml @@ -1,5 +1,10 @@ .npm-dependencies: image: $NODE_IMAGE stage: dependencies + variables: + ADDITIONAL_GLOBAL_PACKAGES: "" + before_script: + - npm install -g $ADDITIONAL_GLOBAL_PACKAGES script: + - "cd $FRONTEND_DIR" - npm install diff --git a/templates/npm/npm-lint.gitlab-ci.yml b/templates/npm/npm-lint.gitlab-ci.yml index dccfd49..bddd8ac 100644 --- a/templates/npm/npm-lint.gitlab-ci.yml +++ b/templates/npm/npm-lint.gitlab-ci.yml @@ -1,9 +1,13 @@ .npm-lint: image: $NODE_IMAGE stage: verify + variables: + ADDITIONAL_GLOBAL_PACKAGES: "" before_script: - script: + - npm install -g $ADDITIONAL_GLOBAL_PACKAGES + - "cd $FRONTEND_DIR" - npm install -g eslint + script: - npm run lint # artifacts: todo add lint results in artifact if posible # expire_in: 2 weeks diff --git a/templates/npm/npm-test.gitlab-ci.yml b/templates/npm/npm-test.gitlab-ci.yml index f97a62b..922c992 100644 --- a/templates/npm/npm-test.gitlab-ci.yml +++ b/templates/npm/npm-test.gitlab-ci.yml @@ -1,8 +1,10 @@ .npm-test: image: $NODE_IMAGE stage: verify + variables: + ADDITIONAL_GLOBAL_PACKAGES: "karma" before_script: - - npm install -g rimraf karma + - npm install -g $ADDITIONAL_GLOBAL_PACKAGES script: - cd $FRONTEND_DIR - npm run test-ci \ No newline at end of file diff --git a/templates/static-analysis/repo-cve-scan-trivy.gitlab-ci.yml b/templates/static-analysis/repo-cve-scan-trivy.gitlab-ci.yml index 7346f6c..e3e6ad6 100644 --- a/templates/static-analysis/repo-cve-scan-trivy.gitlab-ci.yml +++ b/templates/static-analysis/repo-cve-scan-trivy.gitlab-ci.yml @@ -5,9 +5,10 @@ stage: verify needs: [] variables: - SCAN_PATH: "." + SCAN_PATH: $CI_PROJECT_DIR EXITCODE: 1 TRIVY_EXTRA_ARGS: "--no-progress --ignore-unfixed --severity HIGH,CRITICAL" + TRIVY_CKECKS: "vuln,config,secret" cache: paths: - .trivycache/ @@ -16,5 +17,5 @@ junit: junit-report.xml script: # Builds report and puts it in the default workdir $CI_PROJECT_DIR, so artifacts: can take it from there - - trivy --cache-dir .trivycache/ fs --timeout 15m $TRIVY_EXTRA_ARGS --exit-code 0 --security-checks vuln,config --format template --format template --template "/contrib/junit.tpl" -o junit-report.xml $SCAN_PATH - - trivy --cache-dir .trivycache/ fs --timeout 15m $TRIVY_EXTRA_ARGS --exit-code $EXITCODE --security-checks vuln,config $SCAN_PATH + - trivy --cache-dir .trivycache/ fs --timeout 15m $TRIVY_EXTRA_ARGS --exit-code 0 --security-checks $TRIVY_CKECKS --format template --format template --template "/contrib/junit.tpl" -o junit-report.xml $SCAN_PATH + - trivy --cache-dir .trivycache/ fs --timeout 15m $TRIVY_EXTRA_ARGS --exit-code $EXITCODE --security-checks $TRIVY_CKECKS $SCAN_PATH