Skip to content

Repo Setup

The platform is split over two kinds of Git repository: code and config.

flowchart LR
    code["Code<br/>xms-cloud-platform-code<br/>one for all customers"]
    config["Config<br/>one per customer<br/>e.g. xms-cloud-platform-config"]
    config -- "pins release/vX.Y<br/>(entry pipelines)" --> code
    code -. "Layers read<br/>values from" .-> config
Code repository Configuration repository
Name xms-cloud-platform-code One per customer, for example xms-cloud-platform-config (XDEV)
Hosted GitHub Enterprise xebia-managed-services-eu.ghe.com/xmms, synced to customer remotes The customer's Azure DevOps or GitHub
Holds Terraform layers and modules, the Xebia.Mcp PowerShell module, JSON schemas, pipeline templates, the mcp Dockerfile, the Demo configuration mcp.json, *.auto.tfvars, JSON files for firewall, IP groups, App Gateway, WAF, policies and spokes, and the entry pipelines
Changed by Platform developers Platform operators. All standard changes happen here.
Versioned as Release branches release/vX.Y, tags vX.Y.Z main describes what is deployed
Read more Code Config

The configuration repository contains no Terraform. Its entry pipelines check out the code repository at a pinned version and pass the path to an mcp.json.

Spoke files are part of the configuration repository (<env-folder>/spokes/), and the spoke canvas Terraform is part of the code repository. Older versions used four repositories, see Older layouts.

How code reaches customers

  1. Changes are merged to main of the code repository on GitHub Enterprise.
  2. A release branch release/vX.Y is cut and tags vX.Y.Z are created on it.
  3. The trigger-sync.yaml workflow runs on every push to main, release/** and v* tags. It calls the xmms/xms-code-sync dispatcher, which syncs the code repository to the customer remotes.
  4. The customer's configuration repository pins the version in its entry pipelines. See Versioning.

Setting up the repositories for a new customer

Create both repositories in the customer's Azure DevOps project or GitHub organization, bring the released code in, and fill the configuration repository from the template. The steps, the sync target on GitHub, and the protections to switch on at the end are in Prepare the repositories.

Two rules hold in every setup:

  • Nobody edits the code repository on the customer's host. It only receives released branches and tags. Make it read-only for everyone except the sync.
  • All standard changes happen in the configuration repository, through a pull request. Protect the default branch with a required review (a second person), and protect production runs with an approval environment.

While the platform is being implemented, work on a separate initial branch of the configuration repository, and merge it to main when the validation has passed. That way main always describes a configuration that was deployed and checked.

Older layouts

Older versions of the platform used four repositories: platform code and platform config, plus a spoke canvas code and a spoke canvas config repository. In that layout, spoke files lived in spokes/tfspokes/<workload>/ of the spoke config repository, and the self-hosted agents had their own repository. The current layout has the two repositories above. See Migrating from an older platform version.

Other repositories

Repository Role
XMS (Azure DevOps) Previous platform documentation, customer pages and runbooks. Being replaced by this site.
xms-code-sync Dispatcher that syncs the code repository to customer remotes.
pdk-docs This documentation site (MkDocs Material).

The arrow between code and config

A layer in the code repository only reads files from the configuration repository. When you build a new feature, you usually also need new configuration: a new variable in a *.auto.tfvars file or a new JSON property. That is why the code and config sections of this site link to each other: