Skip to main content
The GitHub config source loads Orchestrator configuration directly from a GitHub repository. The source is configured entirely through the MAVERICS_GITHUB_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 GitHub account — with a repository containing Orchestrator configuration
  • A fine-grained personal access token — with Contents read access (see the GitHub deployment provider page for detailed token generation steps)

​
Overview

When the MAVERICS_GITHUB_CONFIG environment variable is set, the Orchestrator fetches its YAML configuration from the specified GitHub repository and file path. The variable contains a JSON payload with repository details and a personal access token for authentication. The Orchestrator supports ETag-based change detection for automatic hot-reload when the configuration file changes in the repository.

​
Use Cases

  • GitOps workflows — manage Orchestrator configuration in Git with full version history, branching, and merge controls
  • Version-controlled config — track every configuration change with commit history and blame annotations
  • PR-based config review — require peer review of configuration changes before they reach production

​
Generating a Personal Access Token

1

Follow the Console Setup Steps

Follow the same steps described in the Console GitHub setup guide, but set Contents to Read-only instead of Read and write. 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_GITHUB_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_GITHUB_CONFIG JSON payload supports the following fields:
FieldTypeRequiredDescription
ownerstringYesGitHub repository owner (user or organization)
repostringYesRepository name
tokenstringYesFine-grained personal access token with Contents read access
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 GitHub 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 GitHub 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_GITHUB_CONFIG='{"token":"<GITHUB_TOKEN>", "owner":"<OWNER_NAME>", "repo":"<REPO_NAME>", "configurationFilePath": "<CONFIG_FILE_PATH>"}'
Replace the placeholder values with your actual certificate paths, GitHub organization or username, repository name, and personal access token.

​
Troubleshooting

  • Authentication failed (401) — verify the personal access token is valid and has not expired. The token needs read access to the repository contents.
  • Repository not found (404) — confirm the owner and repo values are correct. For private repositories, ensure the token has the repo scope.
  • File not found — check the configurationFilePath matches the actual file path in the repository (case-sensitive, relative to the repo root).
  • Config not reloading — ensure MAVERICS_RELOAD_CONFIG=true is set. Note that GitHub API rate limits may affect polling frequency.

Config Sources

Overview of all configuration sources

GitLab

Load config from a GitLab repository

Configuration Reference

Complete configuration field reference

GitHub Deployment Provider

Console-side GitHub setup and personal access token generation