:sourcedir: ../../../../templates

== High Level Architektur.

The entire architektur of the templates build on the following five stages.
they are assumed to be in the following order but don't have to be.

[mermaid]
....
flowchart LR
    Start --> dep(Dependencies)
    dep --> build(Build)
    build --> verify(Verfiy)
    verify --> docs(Documentation)
    docs --> Release
....

=== Dependencies - dependencies
Jobs within this stage are loading all needed Dependencies. This is done for better cache management of Dependencies.

=== Build - build
Jobs within this stage, build all needed artefacts that you need in later stages and for releasing.
In case you need to build multiple artefacts execute following jobs as soon as needed artefacts are build.
Look into Gitlabs https://docs.gitlab.com/ee/ci/yaml/#needs[Needs Documentation].

=== Verify - verify
Jobs within this stage verify your repository functionality.
This is the biggest stage, within most continues integrations.
Verify and Test as much as you can in these Jobs.

=== Documentation - docs
Jobs within this stage build and publish your documentation.

=== Release - release
Jobs within this stage publish your artefacts or automate creating Tags.
For more information look into <<_pipeline_release>>

== About Templates and Pipelines

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`.

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`.

== How to use Templates?

To use our Templates in your project you have to do the following:

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]

====
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]
----
stages:
  - test-image

include:
  - project: 'gilden/ci/gitlab-ci-templates'
    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: $SOME_VARIABLE
#Example overriding scripts
  before_script:
    - echo "my overriding changes"
----

== How to use Pipeline-Templates?

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.


