> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Instance Blueprint Sync

> Share a single Git repository as the source of truth for blueprints across multiple Genesis instances.

## Overview

Multiple Genesis instances can share a single Git repository as the source of
truth for their blueprint catalog. Each instance discovers, runs, and
contributes changes to the same set of blueprints, while every change still
flows through the repository's normal pull-request review on `main`.

This page covers the hub-and-spoke topology: **one shared repository, several
Genesis instances ("pods")**. For per-field reference on the remote repository
form, glob-based include/exclude selectors, sync recovery toasts, and the
rename flow, see
[Blueprint Library and Missions](/docs/Blueprint/Blueprint-Library-And-Missions).

<Info>
  When to use this pattern: your organization runs more than one Genesis
  instance — for example, one per team, environment, or business unit — and
  you want them to share the same authored blueprints rather than maintaining
  parallel copies.
</Info>

## What's supported

| Capability | Behavior |
| - | - |
| Configure the same Git repository as a blueprint source on multiple Genesis instances | Each instance independently clones the repository and registers the blueprints it finds. |
| Authoring inside Genesis | Edits open a pull request against the shared repository. After merge, other instances see the change on their next sync trigger. |
| Authoring outside Genesis | Manual edits committed to the repository's default branch flow into Genesis on demand or at mission-run time. |
| Authentication | Personal Access Token (PAT) per instance, or per-user OAuth, depending on how each Genesis instance's Git connection is configured. |
| Force-push safety | Force-pushes target only the working-copy feature branch. Branch protections on `main` are never violated. |
| Conflict handling | Conflicting pull requests are surfaced through the Git provider's native pull-request UI. |
| Path scope | Edits outside a blueprint's own folder are rejected before the pull request reaches the Git provider. |

<Note>
  GitLab is the most common shared-repo provider for this pattern. GitHub and
  Bitbucket follow the same model where supported by Genesis's managed-repo
  connector for that provider.
</Note>

## Propagation model

Genesis can use **user-present sync** or optional scheduled sync. A merge on
the shared repository is pulled into a given Genesis instance when one of
these triggers fires on that instance:

1. **At mission-run time (automatic).** When a user starts a mission against a
   remote-backed blueprint, Genesis first attempts a best-effort refresh of
   the release copy and then runs the mission against the latest synced
   version. If the refresh fails, the mission can still start from the
   previously synced commit, and Genesis surfaces a warning that names the
   release Genesis used and how recently it was last synced. See
   [Sync recovery and reauthorization](/docs/Blueprint/Blueprint-Library-And-Missions#sync-recovery-and-reauthorization)
   for the toast behavior.
2. **Manual sync (on-demand).** From **Blueprint Library → Remote Repositories**,
   use the **Sync** action on any configured repository to force an immediate
   refresh.
3. **Add or save edits to a repository source (on-demand).** Adding a new
   remote repository, or saving an edit to an existing one, triggers an
   immediate sync.
4. **Scheduled managed-source auto-sync (optional).** An administrator can
   opt a source in with **Sync automatically** on **Config → Managed Sources**.
   See [Managed source automatic sync](/docs/Setup/Advanced-Settings#managed-source-automatic-sync)
   for the schedule settings and defaults.

A merge is picked up on each instance when one of its sync triggers succeeds.
Without scheduled auto-sync enabled for that source, one of the user-present
triggers above must refresh it.

Scheduled auto-sync can also apply Git-managed agent definitions unless
**Auto-promote on sync** is explicitly disabled; see the
[managed-sources API reference](/docs/Genesis-API/API-Reference#unified-managed-sources-api-managed-sources)
for the apply result and waiting reasons.

## Setup

### Step 1 — Prepare the shared repository

1. Create or pick a Git project to act as the shared blueprint repository.

2. Configure a default-branch protection policy that requires pull requests
   into the default branch. Direct pushes to the default branch should be
   blocked.

3. Decide on the folder layout inside the repository. The Genesis convention is:

   ```
   blueprints/<blueprint-name>/blueprint_manifest.yaml
   blueprints/<blueprint-name>/...
   ```

   The top-level folder name (`blueprints`) is configurable per Genesis
   instance via the **Blueprint Root** field. The per-blueprint subfolder and
   the `blueprint_manifest.yaml` filename are fixed.

4. Decide on an authentication mode for each Genesis instance:
   * **Personal Access Token (PAT)** — a shared service-account token,
     configured once per instance as the Git connection. Simplest to set up.
   * **Per-user OAuth** — each end user authorizes Genesis once. More secure
     because each pull request is attributed to its real author and
     revocation is per user, but requires the Git provider's OAuth
     application to be registered and the Genesis OAuth callback configured
     for each instance's hostname.

### Step 2 — Register the repository on each Genesis instance

Repeat these steps **on every Genesis instance** that should share the
repository:

1. Open **Blueprint Library**, then **Remote Repositories** from the header
   actions menu.
2. Choose **Add Repository**. Genesis opens the **Add Remote Repository**
   form.
3. Fill in the form:

| Field | What to enter |
| - | - |
| **Repository ID** | A stable identifier for this repository in Genesis (for example, `acme_blueprints`). The repository ID cannot be changed after creation. |
| **Remote URL** | The HTTPS URL of the shared repository, the same on every instance. Genesis auto-detects the provider (GitHub, GitLab, or Bitbucket) from the host. |
| **Git Connection** | The instance's Git connection used to authenticate against the repository. Genesis suggests a connection by host when one matches. Set up the connection in advance under **Config → Connections**. |
| **Release Ref** | The branch or tag Genesis resolves to current HEAD on each sync. Default: `latest` (resolves to the repository's default branch). You can also enter `main`, a specific tag, or another branch. When you choose an explicit branch, Genesis fetches that branch before resolving its current HEAD. If a tag moves to a different commit on the remote, sync will not use the stale local tag; see the [managed-sources API reference](/docs/Genesis-API/API-Reference#unified-managed-sources-api-managed-sources) for the failure response and recovery. |
| **Scan Types Enabled** | Tick the artifact types this repository holds. Tick **blueprints** for this flow. You can also tick **apps** or **missions** when the repository contains those artifact types. |
| **Blueprint Root** | The folder inside the repository where blueprints live. Default: `blueprints`. Must match the folder layout from Step 1.3. |
| **Auto-promote on sync** | Leave enabled to make synced blueprint changes live automatically. Clear it to save each changed blueprint as a version for an administrator to promote from its **Versions** tab. See [Blueprints with auto-promote off](/docs/Blueprint/Multi-Instance-Skill-Flow-Sync#blueprints-with-auto-promote-off) for how pending versions and rollback work. |
| **Include / Exclude (optional)** | Limit this instance to a subset of the blueprints in the repository. Both fields accept comma-separated blueprint names or selectors. Glob wildcards (`*`, `?`, `[...]`) are supported. See [Remote repository selector matching](/docs/Blueprint/Blueprint-Library-And-Missions#remote-repository-selector-matching) for the full selector format. **Exclude** takes precedence over **Include**. |

4. Genesis scans the repository at the chosen **Release Ref** and shows every
   discovered artifact in the **Scanned Artifacts** preview grid. Deselect any
   cards you want to add to the **Exclude** list before saving.
5. Save the form. Genesis performs an initial sync and registers the
   discovered blueprints in the library on this instance.

That's it. Each instance now tracks the same repository independently. Edits
authored on any instance flow back to the shared repository as pull requests,
and merges on the default branch flow into other instances on their next
sync trigger.

<Tip>
  Different instances can use different **Include** / **Exclude** filters
  against the same repository. For example, a team-A instance can include
  `blueprint:team-a/*` and `blueprint:shared/*`, while a team-B instance
  includes `blueprint:team-b/*` and `blueprint:shared/*`. Each instance
  registers only the subset it cares about.
</Tip>

## Authoring flow

Once instances are registered, day-to-day authoring works like this:

1. A user with edit access opens a remote-backed blueprint inside Genesis and
   edits files in a working copy.
2. The user clicks **Open Pull Request**. Genesis pushes a feature branch to
   the shared repository and opens a pull request.
3. A reviewer merges the pull request in the Git provider's normal review UI.
4. On any other Genesis instance, the next sync trigger (mission start,
   manual sync, or save on the repository source) pulls the merged commit and
   updates the registered blueprint.

For renaming an existing blueprint, see
[Rename a blueprint](/docs/Blueprint/Blueprint-Library-And-Missions#rename-a-blueprint).
For remote-backed blueprints, the rename opens a pull request against the
managed repository and becomes effective after that pull request is merged
and the next sync runs on each instance.

## Limitations to plan for

* **Per-instance access controls.** Role assignments (RBAC) are stored per
  Genesis instance. When one instance picks up a blueprint authored on
  another instance, it applies its own default access grants. If you require
  identical access policy across instances, manage that policy out of band.
* **No automatic rebase of in-flight working copies.** When the default
  branch advances while a working copy is open, the working copy does not
  rebase automatically. Conflicts surface at pull-request merge time through
  the Git provider's standard conflict UX.
* **Concurrent edits across instances are arbitrated by the Git provider, by
  design.** Two users on two different Genesis instances can open working
  copies on the same blueprint at the same time. Whichever pull request
  merges second resolves the conflict the same way any two developers
  resolve a conflicting pull request. Genesis does not add a separate
  cross-instance lock.

## Related pages

* [Blueprint Library and Missions](/docs/Blueprint/Blueprint-Library-And-Missions)
* [Blueprint Branching & Early Completion](/docs/Blueprint/Blueprint-Branching)
* [Connections](/docs/Setup/Connections)