> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Arbeiten mit GitLab

> Mit dem GitLab-Repository des Shops arbeiten: Zugriff auf gitlab.websale.cloud sowie Versionierung der Layout- und Template-Dateien einrichten.

Zu jedem Shop wird im Standard ein eigenes GitLab-Repository mitgeliefert. Dieses Repository dient zur Verwaltung und Versionierung der Layout- und Template-Dateien, die für das Erscheinungsbild des Shops verantwortlich sind.

***

## Zugriff

Das WEBSALE GitLab ist unter folgender URL erreichbar: [https://gitlab.websale.cloud](https://gitlab.websale.cloud)

Die Zugangsdaten werden beim Bereitstellen des Shops durch die WEBSALE AG übermittelt.\
Für zusätzliche Benutzer kann über das Beauftragungsportal der WEBSALE AG ein weiterer Zugriff beantragt werden.

***

## Einstellungen (Settings → CI/CD → Variables)

Im Menü des Projekts unter Settings → CI/CD → Variables sind Umgebungsvariablen für die Shop-Pipeline definiert.

### Editierbare Variablen

| **Variable**             | **Beschreibung**                                                                                                                                                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTO_COMPILE_TEMPLATES` | Steuert, ob Templates nach Veröffentlichung im Main-Branch automatisch kompiliert werden.   <br />- `true`: automatische Kompilierung beim Merge in *main*<br /> - `false`: manuelle Kompilierung über das Admin Interface (Templates & Inhalte → Templates kompilieren). |
| `TEMPLATE_COMPILE_URL`   | URL des Shops, über die die Kompilierung ausgeführt wird.   <br />Diese URL muss bei Domainänderungen (z. B. Livegang von `shop-test.websale.net` auf `ihr-shop.de`) angepasst werden, da der Kompilierungsdienst nur über die aktive Shopdomain erreichbar ist.          |

<Info>
  Angaben zu *Type*, *Environment*, *Visibility Flags* und *Key* dürfen für diese Variablen nicht verändert werden. Änderungen an diesen Einstellungen können zu Störungen oder Fehlern der Pipeline führen.
</Info>

### Readonly Variablen

Diese Variablen können aktuell nur durch Mitarbeiter der WEBSALE AG bearbeitet werden.

| **Variable**                | **Beschreibung**                                                                                                                                                                                                                                                                                      |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TEMPLATE_COMPILE_PASSWORD` | Passwort des Admin Interface Benutzers, der in `TEMPLATE_COMPILE_USER` hinterlegt ist.                                                                                                                                                                                                                |
| `TEMPLATE_COMPILE_USER`     | Benutzername des Admin Interface Benutzers.  <br />Der `Template_Compile_User` ist ein separater technischer Benutzer im Admin Interface, der ausschließlich für die GitLab Pipeline vorgesehen ist.  <br />Persönliche Admin-Logins werden dadurch nicht in GitLab hinterlegt und bleiben geschützt. |
| `S3_TEMPLATES_BUCKET`       | `template`-Bucket im S3.                                                                                                                                                                                                                                                                              |
| `S3_MEDIA_BUCKET`           | `media`-Bucket im S3.                                                                                                                                                                                                                                                                                 |
| `S3_ENDPOINT`               | URL des S3-Storages.                                                                                                                                                                                                                                                                                  |
| `AWS_DEFAULT_REGION`        | Vorgegebene S3-Region von WEBSALE.                                                                                                                                                                                                                                                                    |
| `AWS_SECRET_ACCESS_KEY`     | Zugangsdaten für den Zugriff auf den S3-Speicher.                                                                                                                                                                                                                                                     |
| `AWS_ACCESS_KEY_ID`         | Zugangsdaten für den Zugriff auf den S3-Speicher.                                                                                                                                                                                                                                                     |

***

## Verzeichnis- & Dateistruktur (Root-Ebene)

Das Repository enthält auf Root-Ebene folgende Einträge im Standard:

* `media/` (Verzeichnis)
* `templates/` (Verzeichnis)
* `.gitlab-ci.yml` (Datei)
* `README.md` (Datei)

### media

Das Verzeichnis `media` enthält alle statischen Ressourcen, die für das Design und Layout des Shops verwendet werden. Es ist im Standard wie folgt aufgebaut:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
media
 └── themes
      └── default
           ├── favicon
           ├── fonts
           │    └── bootstrap
           ├── images
           ├── pdf
           ├── scripts
           └── scss
```

| **Verzeichnis** | **Beschreibung**                                                                                                                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `favicon`       | Icons und Favicons für den Browser                                                                                                                                                                                                            |
| `fonts`         | Schriftdateien (z. B. Bootstrap-Fonts)                                                                                                                                                                                                        |
| `images`        | Layoutgrafiken (z. B. Logos, Icons, Banner)                                                                                                                                                                                                   |
| `pdf`           | Statische PDF-Dateien (z. B. AGBs oder Datenschutzerklärung)                                                                                                                                                                                  |
| `scripts`       | JavaScript-Dateien                                                                                                                                                                                                                            |
| `scss`          | SCSS-Quelldateien für CSS  Die kompilierten CSS-Dateien, die aus SCSS generiert werden, sind nicht Bestandteil des Repositories. Diese Dateien können bei Bedarf zu Debug-Zwecken über den Browser bzw. die Browserkonsole eingesehen werden. |

Unterhalb des Verzeichnisses `media/` können Ordner und Dateien nach Bedarf umbenannt, gelöscht oder neu angelegt werden. Diese Änderungen werden von der Pipeline beim Deployment berücksichtigt.

Beim Umbenennen oder Verschieben bestehender Ordner müssen ggf. auch die entsprechenden Pfadangaben in Templates, Stylesheets oder Skripten angepasst werden, damit Ressourcen weiterhin korrekt geladen werden.

### templates

Das Verzeichnis `templates` enthält die für das Shop-Frontend relevanten Template-Dateien. Es ist im Standard wie folgt aufgebaut:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
templates
 ├── components
 ├── layouts
 ├── mails
 └── views
```

| **Verzeichnis** | **Beschreibung**                                                |
| --------------- | --------------------------------------------------------------- |
| `components`    | Wiederverwendbare Template-Bausteine, HTML-Snippets und Widgets |
| `layouts`       | Grundlayouts und Seitenstrukturen                               |
| `mails`         | E-Mail-Vorlagen                                                 |
| `views`         | Ansichten einzelner Shopseiten                                  |

Unterhalb des Verzeichnisses `templates/` können Ordner und Dateien nach Bedarf umbenannt, gelöscht oder neu angelegt werden. Diese Änderungen werden von der Pipeline beim Deployment berücksichtigt.

Beim Umbenennen oder Verschieben bestehender Ordner müssen ggf. auch die verwendeten Pfade in den Templates angepasst werden, damit die entsprechenden Includes, Layouts und Views weiterhin gefunden werden.

### gitlab-ci.yml

Diese Datei definiert die CI/CD-Pipeline (Continuous Integration / Deployment) in Gitlab.

**Standardinhalt**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
### DO NOT EDIT THIS FILE! ###
### CHANGES CAN DESTROY THE SHOP! ###

include:
  - remote: 'https://websale.de/git-design/ws_design/templates.yml'
```

Die hinter `remote:` angegebene Datei bindet die zentrale Pipeline-Vorlage der WEBSALE AG ein. Diese Remote-Datei kann ausschließlich durch die WEBSALE AG bearbeitet werden.

### Funktionsweise der WEBSALE Pipeline

Die Pipeline wird ausschließlich durch Commits im `main`-Branch gestartet und führt dabei folgende Jobs aus:

1. **Build (compile-sass)**

* Überwacht Änderungen in `media/themes/default/scss/**`
* Kompiliert SCSS-Dateien zu CSS (`media/themes/default/styles/`)

2. **Deploy (deploy-css)**

* Synchronisiert das CSS-Verzeichnis mit dem entsprechenden S3-Bucket
* Ausgenommen sind bestimmte Unterverzeichnisse (z. B. Fonts, Scripts, Favicons)

3. **Deploy (deploy-media-without-css)**

* Synchronisiert den übrigen `media`-Ordner (ohne Styles-Verzeichnis) mit dem S3-Bucket

4. **Deploy (deploy-templates)**

* Überträgt das Verzeichnis `templates` in den S3-Bucket
* Führt optional (abhängig von `AUTO_COMPILE_TEMPLATES`) die Template-Kompilierung über die API des Shops durch

Der Status der Pipeline sowie Log-Ausgaben der einzelnen Jobs können im GitLab unter **Build → Pipelines** eingesehen werden.

### README.md

Datei mit weiterführenden Informationen zum WEBSALE GitLab und dem WEBSALE Shopsystem.

***

## Eigene Versionsverwaltung verwenden

Verfügen Sie bereits über eine eigene Versionsverwaltung, die Sie für die Entwicklung des WEBSALE-Shops nutzen möchten (z. B. GitHub, eigenes GitLab, o. Ä.), ist dies grundsätzlich möglich.

**Funktionsprinzip**

* Die Entwicklung findet wie gewohnt in Ihrer bestehenden Versionsverwaltung statt.
* Über eine eigene Pipeline (oder manuell per Git-Remote) werden die relevanten Dateien in das zugehörige WEBSALE GitLab-Projekt übertragen und dort in den Branch `main` gepusht bzw. gemerged.
* Ab diesem Zeitpunkt greift die im WEBSALE GitLab-Projekt hinterlegte Pipeline und übernimmt wie gewohnt Build und Deployment (z. B. SCSS-Kompilierung, Medien- und Template-Deployment auf S3).

Für das Pushen in das WEBSALE GitLab-Projekt werden folgende Voraussetzungen benötigt:

* Ein GitLab-Benutzer für das betreffende WEBSALE Shop-Projekt mit Schreibrechten auf das Projekt bzw. den Branch `main`. Der notwendige Zugang wird durch die WEBSALE AG bereitgestellt.

Die Verwendung eines eigenen Repositories ersetzt nicht die Einrichtung des WEBSALE GitLab-Projekts. Die initiale Einrichtung des Projekts und der Benutzer kann derzeit nicht vollständig selbstständig vorgenommen werden und erfolgt vorerst über die WEBSALE AG.

***

## Hinweise & Einschränkungen

* Über das GitLab-Repository besteht kein Zugriff auf Produktdaten (z. B. Produkte, Preise, Bilder) oder Kundendaten. Produkt- und Kundendaten können über das Admin Interface, [REST APIs](/schnittstellen/admin-interface-api), Connectoren etc. verwaltet werden.
* Das Repository dient zur Verwaltung und zum Deployment von Shop-Templates und den dazugehörigen Mediendateien.
* Eigene Prozesse wie z. B. Docker-Container, zusätzliche Build-Jobs oder externe Programme sind mit der Standard-Pipeline nicht vorgesehen.
* Die Standard-Pipeline arbeitet aktuell ausschließlich im Branch `main`.
* Die Deployment-Jobs synchronisieren nur die Verzeichnisse `media` und `templates`. Oberhalb dieser Verzeichnisse angelegte Ordner werden nicht übertragen.

***

## Zugriff auf den Objektspeicher (S3)

Über GitLab besteht nur Zugriff auf die Shop-Templates bzw. das Theme/Template-Repository. GitLab ist damit der zentrale Ort für die Versionsverwaltung und die Bearbeitung des Template-Codes (z. B. Anpassungen am Frontend, Layouts, Komponenten, Styles).

Neben dem Zugriff über GitLab existiert zusätzlich ein Zugriff auf den Objektspeicher des Shops (S3). Über diesen Zugang erhält man Zugriff auf alle Dateien des Shops, z.B. Produktbilder, [JSON-Dateien](/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert) etc.