Skip to content

GitOps-driven configuration

You will register a Git repository as a read-only configuration source. Every commit on the tracked branch that changes a tracked YAML file becomes a new Ampora draft version, ready for review and rollout.

Time: ~ 10 minutes.

When to use this

  • You already version your collector configs in Git (most teams do).
  • You want PR-reviewable changes, with audit-by-commit-hash.
  • You want identical content between staging and production by default.
  • You are happy with read-only sync today; UI edits are blocked for Git-controlled configurations in this tranche.

The reverse path (UI edits → automatic PR proposals) and webhook-driven near-real-time sync land in a later phase, see ADR-049. Polling, the default mode, is sufficient for production: the median latency is under 60 seconds.

Prerequisites

  • A Git repository accessible from the Ampora server (HTTPS or SSH).
  • A branch (main is fine) and a path glob (configs/**/*.yaml is a good start).
  • A credential if the repo is private:
  • Personal Access Token for HTTPS, or
  • an SSH private key for SSH clone URLs.

1. Prepare the repo

A minimal layout:

my-otel-configs/
├── configs/
│   ├── edge/
│   │   ├── prod.yaml
│   │   └── staging.yaml
│   └── core/
│       └── tier-1.yaml
└── README.md

Each YAML file becomes one Ampora Configuration. The configuration name is derived from:

  • the # ampora.name: <name> frontmatter on the first line, if present, or
  • the filename without extension (prod, staging, tier-1).

Use the frontmatter form if filenames could collide.

2. Register the source

In Ampora:

  1. GitOps → New source.
  2. Fill in:
  3. Name: my-otel-configs.
  4. Repository URL: git@gitlab.example.com:platform/my-otel-configs.git.
  5. Branch: main.
  6. Path glob: configs/**/*.yaml.
  7. Poll interval: 60 seconds.
  8. Credential kind: SshKey (or Pat, or None for public).
  9. Paste the SSH private key (PEM format) or the PAT.
  10. Save.

The plaintext credential is wrapped immediately by Ampora's IKeyProtector (AES-GCM-256 by default, or your configured HSM/KMS) and never stored or logged in plaintext after that point. There is no read-back path. To rotate, delete the source and recreate it.

3. Trigger the first sweep

You can either wait up to PollIntervalSeconds or click Sync now. The Status column flips through Syncing → Active.

After the sweep:

  • Each tracked file appears as a Configuration in the Configurations page, source = Git.
  • Its first published version content matches the file content.
  • The configuration's edit screen is read-only with a "Managed by GitOps" banner pointing at the Git source.

4. Make a commit and watch it land

In your repo:

git checkout -b feature/raise-batch
sed -i 's/send_batch_size: 1024/send_batch_size: 2048/' configs/edge/prod.yaml
git commit -am "edge/prod: raise batch size to 2048"
git push origin feature/raise-batch

Open a merge request, review (the validator and linter will rerun on the new draft once it lands), merge to main. Within PollIntervalSeconds seconds Ampora notices the new tip commit.

In GitOps → my-otel-configs → Sync runs you see:

  • Files imported: 1
  • New versions: 1 (edge-prod v2)
  • Tip commit: <sha> with the commit message from your MR

The new draft is ready to roll. From here it is a normal rollout (Run a canary rollout) — GitOps changed where the content came from, nothing else.

5. Read the sync runs

Each sweep writes a GitSyncRun row. The UI surface keeps 30 days of runs. Each row has:

  • start / finish UTC,
  • tip commit and parent,
  • files-processed / files-imported / errors-encountered,
  • per-file errors (broken YAML, content larger than the configured limit, etc.) collected as JSON.

Failed files do not abort the sweep — Ampora prefers partial progress on a 50-config repo over all-or-nothing.

6. Pause or rotate

  • Pause — the source row has a Status: Paused toggle. The sweeper skips paused sources entirely. Useful during a maintenance window or when you want to detach the GitOps wiring temporarily.
  • Rotate credential — credentials cannot be edited in place. Delete and recreate the source. Existing imported configurations are left alone.

What you learned

  • How to register a Git repo as a configuration source.
  • How file-to-configuration naming works (frontmatter or filename).
  • How read-only sync interacts with the Configurations editor.
  • Where to find sync-run history when something does not show up.

Next