---
icon: material/github
---

The 10x Engine employs a [GitOps](https://doc.log10x.com/engine/gitops/) approach to configuration management, offering a secure, version-controlled solution across distributed environments.

The `@github` launch macro enables the engine to pull YAML config, JavaScript, text/geo lookup, and Symbol library files from GitHub at startup.

The engine can poll the remote branch for changes at a specified interval (e.g., 5min),
allowing distributed 10x apps to synchronize and reload updated configurations.

Pulled files are extracted to a temporary directory (archives are automatically unpacked).

!!! tenx-k8sinitializer "k8s"

    When deploying 10x apps to k8s, the provided Helm charts can use [init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/){target="_blank"}
    to pull configuration from GitHub, enabling container immutability.

    To learn more, see the deployment procedure for your specific app under [apps](https://doc.log10x.com/apps/).

### :simple-yaml: Config

To specify a `@GitHub` launch macro via a [YAML](https://doc.log10x.com/config/yaml/) config file:

``` yaml
include:

tenx: run

- source: github

  options:

    # 'enabled' controls whether to enable this pull config
    enabled: true

    # 'token' specifies an access token for accessing the Github repo.
    #  To learn more see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
    token: $=TenXEnv.get("GH_TOKEN")

    # 'repo' specifies the GitHub user/repo name from which to pull files
    repo: my-user/my-repo

    # 'branch' on 'repo' (if null, use repo default branch)
    branch: main

     # 'paths' specifies Glob patterns within 'repo' to pull and extract to a temp folder.
    paths:
      - config/*.yaml     # https://doc.log10x.com/config/yaml
      - symbols/*.10x.tar # https://doc.log10x.com/run/symbol
      - lookups/*.csv     # https://doc.log10x.com/api/js/#TenXLookup
      - scripts/*.js      # https://doc.log10x.com/api/js/

    # 'syncInterval' specifies an interval by which to poll the remote branch for updates, set null for none.
    syncInterval: 5min
```

### :octicons-command-palette-24: CLI

You can specify a `@github` launch macro via the [CLI](https://doc.log10x.com/config/cli/)
as a JSON object by [bash-escaping](https://www.baeldung.com/linux/bash-escape-characters) its contents.

For example:

``` console
$ tenx run '@github={"token": "<replace-me-with-gh-token>", "repo": "my-user/my-repo", "branch": "main", "paths": ["config/*.yaml", "symbols/*.10x.tar", "lookups/*.csv", "scripts/*.js"], "syncInterval": "2min"}'
```

### :material-source-branch: Shipped pulls

The 10x apps ship a GitOps config, [gitops/config.yaml](https://github.com/log-10x/config/blob/main/pipelines/gitops/config.yaml){target="_blank"}, with two `@github` pulls from one repo. Each is off until its environment variable turns it on. Both read the repo from `GH_REPO` (`owner/repo`, required once either pull is on), the branch from `GH_BRANCH` (default `main`) and the token from `GH_TOKEN`, and poll every `GH_SYNC_INTERVAL` (default `30s`).

- **Policy files, `GH_ENABLED=true`:** pulls `log10x/policy/*.csv` (`caps.csv`, `actions.csv`, `totals.csv` and `config-generation.csv`) and copies them to a stable folder, `GH_DEST` (default `${java.io.tmpdir}/tenx/github`). The [rate regulator](https://doc.log10x.com/run/receive/rate/)'s cap, action, total and config-generation files default to those copies, and each sync rewrites them in place, so the regulator reloads them. The `log10x/policy` folder must exist on the branch and hold `caps.csv` when the engine starts. When the Log10x MCP's budget run delivers through git, it commits these files directly to a dedicated branch, `log10x-policy` by default; set `GH_BRANCH` to that branch.
- **Other files, `GH_FILES_ENABLED=true`:** pulls the CSVs its `paths` glob names from the same repo, for lookups such as the compact receiver's or a mute file. The shipped glob is `test/*.csv`; edit `paths` in a fork of the config to pull other folders. With `GH_DEST` set the files land beside the policy files, and with it unset they stay in the pull cache.

Turn on one source for the regulator's files: with `GH_ENABLED=true` the policy copies win over the [Kubernetes ConfigMap](k8s.md)'s.