Skip to main content

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

​
What’s supported

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.

​
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 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 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 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:
    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:
  1. 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.
  2. 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.
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.

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