Skip to main content
Brand Atlas’s content for each atlas is stored in a per-tenant GitHub repository. Each atlas has its own repo; the repo contains MDX files for each section and Horizon, asset files in a structured folder, and a manifest. The portal reads from the repo; edits made in the portal write back to it. This model is invisible to most brand owners and is mainly useful for agencies, technical teams, and anyone running multiple atlases at scale.
This is an advanced page. Most brand owners do not need to know any of this. The visual editor and MDX upload paths work without ever touching the underlying repository.

​
Why a repo per atlas

Three reasons:
  1. Version control comes free. Git is the most thoroughly tested version-control system in the world; every change to the brand record is a commit, with author, date, and diff.
  2. External authoring is supported natively. A studio authoring a Horizon as MDX can do it in their normal Git workflow and push to the atlas’s repo. Brand Atlas picks up the change.
  3. Multi-atlas operations are tractable. An agency running 30 client atlases has 30 repos. Standard Git tooling applies: scripted operations, batch updates, cross-atlas search.
The repo is not a separate place to manage; the portal is the primary surface. The repo is the storage substrate.

​
The repo structure

A typical atlas repo looks like this: 
brand-atlas-acme/
├── atlas.json                  # Atlas manifest
├── sections/
│   ├── logo-and-identity.mdx
│   ├── typography.mdx
│   ├── colour-system.mdx
│   ├── applications.mdx
│   ├── strategy.mdx
│   ├── voice.mdx
│   ├── photography.mdx
│   └── social.mdx
├── horizons/
│   ├── active/
│   │   ├── spring-2026-campaign.mdx
│   │   └── arabic-typography.mdx
│   └── archived/
│       └── q4-2025-campaign.mdx
├── assets/
│   ├── logo/
│   │   ├── primary.svg
│   │   ├── primary-dark.svg
│   │   └── ...
│   ├── photography/
│   └── files/
└── history/
    └── (auto-generated)
atlas.json carries the atlas’s identity (name, tier, audience defaults, integration metadata). The sections/ directory holds the eight standard sections. horizons/active/ and horizons/archived/ hold Horizons by status. assets/ is where uploaded files live. history/ is auto-generated by Brand Atlas to support the brand record’s history view.

​
How the portal reads and writes

The portal reads the repo on demand and caches results. On a brand-owner edit:
  1. The portal commits the change as a new commit on the main branch, attributed to the brand owner.
  2. The cache for that section invalidates.
  3. The next read returns the new state.
The team member’s view updates within seconds. The commit history shows the change forever.

​
Accessing the repo

Most customers never access the repo directly. For customers who want to:
  • Guardian tier required. The per-tenant repo access is a Guardian feature.
  • Enable repo access. Settings → Advanced → Repo access. Brand Atlas provisions a deploy key for your team.
  • Clone the repo. Standard Git operations work.
The repo is the customer’s repo; you can clone, branch, push, pull, run scripts against it. The portal reflects what is on the main branch within seconds of any push.

​
Authoring workflows

Three workflows the per-tenant repo unlocks:

​
1. MDX authoring in the studio’s normal tools

The studio authors a Horizon in VS Code, commits it locally, pushes to the atlas repo’s main branch. The portal picks up the change and the Horizon appears. This is the most common power-user workflow. The studio’s tools (editor extensions, linters, spell-check, version control) all apply. The portal is the publication surface; the authoring happens in the studio’s environment.

​
2. CI/CD against the brand record

A custom CI workflow can validate the brand record on every commit: link-checking, schema validation, custom voice rules, asset checks. The CI runs as a GitHub Action on the repo. Useful for agencies maintaining many atlases who want to enforce shared rules.

​
3. Cross-atlas scripting

An agency running multiple atlases can script across them. A change to a shared partnership Horizon can be applied to multiple atlases with a single script. The atlases each remain independent; the scripting is a convenience. Cross-atlas scripting is the most advanced of the workflows. The benefit is significant for large multi-tenant teams; the setup investment is also significant.

​
Limitations

The per-tenant repo model has trade-offs:
  • Conflicts. When the same section is edited concurrently in the portal and via Git, the second commit wins. Brand Atlas does not attempt to merge concurrent edits.
  • Large binary assets. Git is not great with very large binary files. Brand Atlas stores large assets in object storage and keeps the repo for text-shaped content; for repo-direct workflows, large assets should be referenced rather than committed.
  • Repo size. Atlases with very large histories may produce large repos. Brand Atlas archives history beyond the tier’s retention window to a separate location.

​
Security model

The repo is:
  • Private. Not visible to the public.
  • Scoped to the atlas. A repo for one atlas does not have access to any other.
  • Customer-controlled. The customer can revoke Brand Atlas’s access to their own repo at any time, which detaches the portal from the storage. Detaching is irreversible; do not do it without understanding the consequences.

​
When this matters and when it does not

For most brand owners, the repo is plumbing. The portal works without the customer ever knowing it exists. For agencies running multiple atlases, the repo unlocks scripted operations. For technical teams who already work in Git and want to keep their authoring workflow, the repo is the bridge. For studios authoring on behalf of customers, the repo is the delivery mechanism. If you do not recognise yourself in any of those four cases, you can safely ignore this page.

Authoring in MDX

The MDX reference.

Local previews and CI

Working from the command line.

Managing multiple atlases

Multi-atlas patterns.