Skip to main content
The GitLab config source loads Orchestrator configuration directly from a GitLab repository. This source supports both GitLab.com and self-hosted GitLab instances. 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
  • Self-hosted GitLab — connect to on-premises GitLab instances for air-gapped or regulated environments

​
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

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

​
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
configurationFilePathstringYesPath to the config file within the repository
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.
  • Self-hosted GitLab — ensure the Orchestrator can reach the GitLab instance’s API endpoint over the network.
  • 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