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

# GitLab

The GitLab config source loads Orchestrator configuration directly from a GitLab.com repository. The source is configured entirely through the `MAVERICS_GITLAB_CONFIG` environment variable.

<Note>
  **Console terminology:** In the Maverics Console, Orchestrator instances and
  configuration delivery are managed through **Deployments**. When working directly
  with YAML, configuration is managed as files delivered via the `-config` flag or
  `MAVERICS_CONFIG` environment variable.
</Note>

## Prerequisites

* **A GitLab account** -- with a project containing Orchestrator configuration
* **A personal access token** -- with `read_repository` scope (see the [GitLab deployment provider](/reference/console/config-publishing/gitlab#generate-a-personal-access-token) page for detailed token generation steps)

## Overview

When the `MAVERICS_GITLAB_CONFIG` environment variable is set, the Orchestrator fetches its YAML configuration from the specified GitLab project and file path. The variable contains a JSON payload with project details, authentication token, and optional branch selection. The Orchestrator supports ETag-based change detection for automatic hot-reload.

## Use Cases

* **GitOps with GitLab** -- manage Orchestrator configuration in GitLab with full version history and merge request workflows
* **CI/CD pipeline integration** -- publish validated configuration as part of GitLab CI/CD pipelines
* **Merge request workflows** -- require peer review of configuration changes through GitLab merge requests before they reach production

## Generating a Personal Access Token

<Steps>
  <Step title="Follow the Console Setup Steps">
    Follow the same steps described in the [Console GitLab setup guide](/reference/console/config-publishing/gitlab#generate-a-personal-access-token), but only check **`read_repository`** instead of both scopes. The Orchestrator only needs to read configuration, not write it.
  </Step>

  <Step title="Use the Token in Configuration">
    Copy the generated token value and use it as the `token` field in the `MAVERICS_GITLAB_CONFIG` environment variable (see Configuration below).
  </Step>
</Steps>

## Configuration

The GitLab config source is configured via the `MAVERICS_GITLAB_CONFIG` environment variable with a JSON payload:

```bash theme={null}
export MAVERICS_GITLAB_CONFIG='{
  "namespace": "my-group",
  "repo": "orchestrator-config",
  "branch": "main",
  "token": "glpat-...",
  "configurationFilePath": "path/to/config"
}'
maverics
```

## Configuration Reference

The `MAVERICS_GITLAB_CONFIG` JSON payload supports the following fields:

| Field                   | Type   | Required | Description                                                                                                                                                                                        |
| ----------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `namespace`             | string | Yes      | GitLab namespace (group or user)                                                                                                                                                                   |
| `repo`                  | string | Yes      | Project name                                                                                                                                                                                       |
| `branch`                | string | No       | Branch to read from (default: the project's default branch)                                                                                                                                        |
| `token`                 | string | Yes      | Personal access token with `read_repository` scope                                                                                                                                                 |
| `configurationFilePath` | string | No       | Directory path prefix within the repository where the config bundle is stored. The Orchestrator appends `maverics.tar.gz` to this path. If omitted, the bundle is expected at the repository root. |

**ETag-based hot-reload:** When `MAVERICS_RELOAD_CONFIG=true` is set, the Orchestrator periodically checks the file's ETag via the GitLab API. When the file is updated (via commit), the Orchestrator detects the ETag change and reloads the configuration automatically.

## Full Environment Example

A complete `maverics.env` file for an Orchestrator using GitLab as its config source:

```bash maverics.env theme={null}
MAVERICS_DEBUG_MODE=true
MAVERICS_HTTP_ADDRESS=:443
MAVERICS_TLS_SERVER_CERT_FILE=your-cert.pem
MAVERICS_TLS_SERVER_KEY_FILE=your-private_key.pem
MAVERICS_RELOAD_CONFIG=true
MAVERICS_POLLING_INTERVAL_SECONDS=30
MAVERICS_BUNDLE_PUBLIC_KEY_FILE=./public_key.pem
MAVERICS_GITLAB_CONFIG='{"token":"<GITLAB_TOKEN>", "namespace":"<ORGANIZATION_NAME>", "repo":"<REPO_NAME>", "branch":"<BRANCH_NAME>", "configurationFilePath": "<CONFIG_FILE_PATH>"}'
```

Replace the placeholder values with your actual certificate paths, GitLab namespace, project name, branch, and personal access token.

## Troubleshooting

* **Authentication failed (401)** -- verify the personal access token is valid and has not expired. The token needs the `read_repository` scope.
* **Project not found (404)** -- confirm the `namespace` and `repo` values are correct. For private projects, ensure the token has appropriate access.
* **Wrong branch** -- if `branch` is omitted, the project's default branch is used. Set `branch` explicitly if the config file is on a different branch.
* **GitLab.com only** -- the Orchestrator connects to `gitlab.com`. Self-hosted GitLab instances are not currently supported as a config source.
* **Config not reloading** -- ensure `MAVERICS_RELOAD_CONFIG=true` is set. Check Orchestrator logs for ETag change detection messages.

## Related Pages

<CardGroup cols={2}>
  <Card title="Config Sources" icon="folder-gear" href="/reference/orchestrator/configuration/config-sources">
    Overview of all configuration sources
  </Card>

  <Card title="GitHub" icon="code-branch" href="/reference/orchestrator/configuration/config-sources/github">
    Load config from a GitHub repository
  </Card>

  <Card title="Configuration Reference" icon="code" href="/reference/orchestrator/configuration">
    Complete configuration field reference
  </Card>

  <Card title="GitLab Deployment Provider" icon="gitlab" href="/reference/console/config-publishing/gitlab">
    Console-side GitLab setup and personal access token generation
  </Card>
</CardGroup>