Skip to main content
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.
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.

​
Prerequisites

  • A GitLab account — with a project containing Orchestrator configuration
  • A personal access token — with read_repository scope (see the GitLab deployment provider 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

1

Follow the Console Setup Steps

Follow the same steps described in the Console GitLab setup guide, but only check read_repository instead of both scopes. The Orchestrator only needs to read configuration, not write it.
2

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

​
Configuration

The GitLab config source is configured via the MAVERICS_GITLAB_CONFIG environment variable with a JSON payload: 
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:
FieldTypeRequiredDescription
namespacestringYesGitLab namespace (group or user)
repostringYesProject name
branchstringNoBranch to read from (default: the project’s default branch)
tokenstringYesPersonal access token with read_repository scope
configurationFilePathstringNoDirectory 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:
maverics.env
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.

Config Sources

Overview of all configuration sources

GitHub

Load config from a GitHub repository

Configuration Reference

Complete configuration field reference

GitLab Deployment Provider

Console-side GitLab setup and personal access token generation