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

# Working with GitLab

> Work with the WEBSALE GitLab repository to manage and version layout and template files that control the appearance of your online shop.

By default, every shop is delivered with its own GitLab repository. This repository is used to manage and version the layout and template files responsible for the appearance of the shop.

***

## Access

The WEBSALE GitLab is available at the following URL: [https://gitlab.websale.cloud](https://gitlab.websale.cloud)

The access credentials are provided when the shop is set up by WEBSALE AG.\
Additional access for further users can be requested via WEBSALE AG's commissioning portal.

***

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

In the project menu under Settings → CI/CD → Variables, environment variables for the shop pipeline are defined.

### Editable variables

| **Variable**             | **Description**                                                                                                                                                                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTO_COMPILE_TEMPLATES` | Controls whether templates are automatically compiled after publishing in the main branch.   <br />- `true`: automatic compilation on merge into *main*<br /> - `false`: manual compilation via the Admin Interface (Templates & Content → Compile templates).  |
| `TEMPLATE_COMPILE_URL`   | URL of the shop via which the compilation is executed.   <br />This URL must be adjusted when the domain changes (e.g., going live from `shop-test.websale.net` to `your-shop.de`), since the compilation service is only reachable via the active shop domain. |

<Info>
  Information about *Type*, *Environment*, *Visibility Flags*, and *Key* must not be changed for these variables. Changes to these settings can cause pipeline failures or errors.
</Info>

### Read-only variables

These variables can currently only be edited by WEBSALE AG employees.

| **Variable**                | **Description**                                                                                                                                                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TEMPLATE_COMPILE_PASSWORD` | Password of the Admin Interface user stored in `TEMPLATE_COMPILE_USER`.                                                                                                                                                                                                  |
| `TEMPLATE_COMPILE_USER`     | Username of the Admin Interface user.  <br />The `Template_Compile_User` is a separate technical user in the Admin Interface that is exclusively intended for the GitLab pipeline.  <br />This way, personal admin logins are not stored in GitLab and remain protected. |
| `S3_TEMPLATES_BUCKET`       | `template` bucket in S3.                                                                                                                                                                                                                                                 |
| `S3_MEDIA_BUCKET`           | `media` bucket in S3.                                                                                                                                                                                                                                                    |
| `S3_ENDPOINT`               | URL of the S3 storage.                                                                                                                                                                                                                                                   |
| `AWS_DEFAULT_REGION`        | Default S3 region specified by WEBSALE.                                                                                                                                                                                                                                  |
| `AWS_SECRET_ACCESS_KEY`     | Access credentials for the S3 storage.                                                                                                                                                                                                                                   |
| `AWS_ACCESS_KEY_ID`         | Access credentials for the S3 storage.                                                                                                                                                                                                                                   |

***

## Directory & file structure (root level)

By default, the repository contains the following entries at the root level:

* `media/` (directory)
* `templates/` (directory)
* `.gitlab-ci.yml` (file)
* `README.md` (file)

### media

The `media` directory contains all static resources used for the design and layout of the shop. By default it is structured as follows:

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

| **Directory** | **Description**                                                                                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `favicon`     | Icons and favicons for the browser                                                                                                                                                                    |
| `fonts`       | Font files (e.g., Bootstrap fonts)                                                                                                                                                                    |
| `images`      | Layout graphics (e.g., logos, icons, banners)                                                                                                                                                         |
| `pdf`         | Static PDF files (e.g., terms and conditions or privacy policy)                                                                                                                                       |
| `scripts`     | JavaScript files                                                                                                                                                                                      |
| `scss`        | SCSS source files for CSS  The compiled CSS files generated from SCSS are not part of the repository. If needed, these files can be viewed for debugging purposes via the browser or browser console. |

Below the `media/` directory, folders and files can be renamed, deleted, or newly created as needed. These changes are taken into account by the pipeline during deployment.

When renaming or moving existing folders, the corresponding path references in templates, stylesheets, or scripts may also need to be adjusted so that resources continue to load correctly.

### templates

The `templates` directory contains the template files relevant to the shop frontend. By default it is structured as follows:

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

| **Directory** | **Description**                                               |
| ------------- | ------------------------------------------------------------- |
| `components`  | Reusable template building blocks, HTML snippets, and widgets |
| `layouts`     | Base layouts and page structures                              |
| `mails`       | Email templates                                               |
| `views`       | Views of individual shop pages                                |

Below the `templates/` directory, folders and files can be renamed, deleted, or newly created as needed. These changes are taken into account by the pipeline during deployment.

When renaming or moving existing folders, the paths used in the templates may also need to be adjusted so that the corresponding includes, layouts, and views can still be found.

### gitlab-ci.yml

This file defines the CI/CD pipeline (Continuous Integration / Deployment) in GitLab.

**Default content**

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

The file specified after `remote:` includes WEBSALE AG's central pipeline template. This remote file can only be edited by WEBSALE AG.

### How the WEBSALE pipeline works

The pipeline is triggered exclusively by commits to the `main` branch and runs the following jobs:

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

* Monitors changes in `media/themes/default/scss/**`
* Compiles SCSS files to CSS (`media/themes/default/styles/`)

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

* Synchronizes the CSS directory with the corresponding S3 bucket
* Certain subdirectories (e.g., fonts, scripts, favicons) are excluded

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

* Synchronizes the rest of the `media` folder (without the styles directory) with the S3 bucket

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

* Transfers the `templates` directory to the S3 bucket
* Optionally (depending on `AUTO_COMPILE_TEMPLATES`) performs template compilation via the shop's API

The status of the pipeline and the log output of the individual jobs can be viewed in GitLab under **Build → Pipelines**.

### README.md

File with additional information about the WEBSALE GitLab and the WEBSALE shop system.

***

## Using your own version control

If you already have your own version control system that you would like to use for the development of the WEBSALE shop (e.g., GitHub, your own GitLab, or similar), this is generally possible.

**How it works**

* Development takes place as usual in your existing version control system.
* Via your own pipeline (or manually via a Git remote), the relevant files are transferred to the corresponding WEBSALE GitLab project and pushed or merged into the `main` branch there.
* From this point on, the pipeline stored in the WEBSALE GitLab project takes effect and handles build and deployment as usual (e.g., SCSS compilation, media and template deployment to S3).

The following prerequisites are required to push to the WEBSALE GitLab project:

* A GitLab user for the relevant WEBSALE shop project with write permissions on the project or the `main` branch. The necessary access is provided by WEBSALE AG.

Using your own repository does not replace the setup of the WEBSALE GitLab project. The initial setup of the project and users currently cannot be done fully independently and is handled by WEBSALE AG for the time being.

***

## Notes & limitations

* The GitLab repository does not provide access to product data (e.g., products, prices, images) or customer data. Product and customer data can be managed via the Admin Interface, [REST APIs](/en/schnittstellen/admin-interface-api), connectors, etc.
* The repository is used for managing and deploying shop templates and the associated media files.
* Custom processes such as Docker containers, additional build jobs, or external programs are not supported by the standard pipeline.
* The standard pipeline currently only works on the `main` branch.
* The deployment jobs only synchronize the `media` and `templates` directories. Folders created above these directories are not transferred.

***

## Access to the object storage (S3)

GitLab only provides access to the shop templates or the theme/template repository. GitLab is therefore the central place for version control and editing the template code (e.g., adjustments to the frontend, layouts, components, styles).

In addition to access via GitLab, there is also access to the shop's object storage (S3). This access provides access to all files of the shop, e.g., product images, [JSON files](/en/schnittstellen/externe-datenschnittstelle-datei-bucket-basiert), etc.