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

# GitHub

The GitHub config source loads Orchestrator configuration directly from a GitHub repository. The source is configured entirely through the `MAVERICS_GITHUB_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.

## 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](/reference/console/config-publishing/github#generate-a-fine-grained-personal-access-token) 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](/reference/console/config-publishing/github#generate-a-fine-grained-personal-access-token), 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

The GitHub config source is configured via the `MAVERICS_GITHUB_CONFIG` environment variable with a JSON payload:

```bash theme={null}
export MAVERICS_GITHUB_CONFIG='{
  "owner": "my-org",
  "repo": "orchestrator-config",
  "token": "ghp_...",
  "configurationFilePath": "path/to/config"
}'
maverics
```

## Configuration Reference

The `MAVERICS_GITHUB_CONFIG` JSON payload supports the following fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `owner` | string | Yes | GitHub repository owner (user or organization) |
| `repo` | string | Yes | Repository name |
| `token` | string | Yes | Fine-grained personal access token with Contents read access |
| `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 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:

```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_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 directory path in the repository (case-sensitive, relative to the repo root). The Orchestrator looks for `maverics.tar.gz` at this path.
* **Config not reloading** -- ensure `MAVERICS_RELOAD_CONFIG=true` is set. Note that GitHub API rate limits may affect polling frequency.

## Related Pages

> **[Config Sources](/reference/orchestrator/configuration/config-sources)**
>
> Overview of all configuration sources

> **[GitLab](/reference/orchestrator/configuration/config-sources/gitlab)**
>
> Load config from a GitLab repository

> **[Configuration Reference](/reference/orchestrator/configuration)**
>
> Complete configuration field reference

> **[GitHub Deployment Provider](/reference/console/config-publishing/github)**
>
> Console-side GitHub setup and personal access token generation