Skip to content

Commit 5188801

Browse files
jefeishjefeish
committed
updated README
1 parent dad3fe8 commit 5188801

File tree

1 file changed

+190
-8
lines changed

1 file changed

+190
-8
lines changed

‎docs/hubSyncHandler/README.md‎

Lines changed: 190 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,208 @@
44

55
## Overview
66

7-
This feature adds a hub‑and‑spoke synchronization capability to Safe Settings.
7+
This adds the **hub‑and‑spoke synchronization capability** to Safe Settings.
88

9-
One central **master admin repository** (the hub) serves as the authoritative source of configuration which is automatically propagated to each organization’s **admin repository** (the spokes).
9+
One central **master admin repository** (the hub) serves as the authoritative source of configuration ('Master' Admin Config Repo) which is automatically propagated to each organization’s **admin repository** (the spokes).
1010

11-
**Note:** When something changes in the central repo, only those changed files are copied to each affected ORG’s admin repo, so everything stays in sync with little manual work.
11+
**Note:** When something changes in the 'Master' repo (the hub), only those changed files are copied to each affected ORG’s admin repo, so everything stays in sync.
1212

1313
## Sync Lifecycle (High Level)
1414

1515
```mermaid
1616
graph TD
17-
A0(PR Closed) --> A1(HUB Admin Repo)
17+
A0(PR Closed Event) --> A1(HUB Admin Repo)
1818
A1(ORG Admin Repo) --> B(ORG Admin Repo)
1919
A1(HUB Admin Repo) --> C(ORG Admin Repo)
2020
A1(HUB Admin Repo) --> D(ORG Admin Repo)
2121
```
2222

23-
## Environment Variables & Inputs
23+
## Gettings Started
2424

25-
Environment variables specific to the 'Sync-Feature'
25+
>**Note:** for the standard setup lets assume that Safe-Settings configuration on the Admin Config Repos (Spokes) are stored in `.github/`
26+
27+
These are the basic steps to setup the Enterprise-Level Safe-Settings, using **Hub-sync** support.
28+
29+
### ✅ Step 1: Register the App
30+
**Register the Safe-Settings App** in your Enterprise (Enterprise App) or in your Organization.
31+
32+
For App "installation tragets" (Where can this GitHub App be installed?)
33+
Choose ***Any account***
34+
35+
### ✅ Step 2: Install the App
36+
**Install the Safe-Settings App** in any Organzation that you would like Safe-Settings to manage.
37+
38+
### ✅ Step 3: Create the 'Org-Level' Safe-Settings Admin Config Repo (Spokes)
39+
Create the Org-Level Repo that is your dedicated Safe-Settings Config Repo and will hold all Safe-Settings configurations for the Org.
40+
41+
### ✅ Step 4: Create the 'Master' Safe-Settings Admin Config Repo (Hub)
42+
Choose any Organization where the Safe-Settings App is installed and create a 'Master' Safe-Settings Admin Config Repo.
43+
44+
The Repository requires a standard directory structure for storing the config data:
45+
```bash
46+
.github/
47+
└─ safe-settings/
48+
├── globals/
49+
│ └── manifest.yml
50+
└── organizations/
51+
├── org1/
52+
│ └── ...yml
53+
└── org2/
54+
└── ...yml
55+
```
56+
57+
Notes:
58+
- The `manifest.yml` is a required file, that defines rules for syncing **Global** Safe-Settings configurations. We will address the content format later.
59+
- `org1` and `org2` are just examples and should be replaced with the real names of the Orgs that you want to manage with the **Hub-Sync**.
60+
61+
### ✅ Step 5: Configure the 'Master' Safe-Settings Admin Config Repo (Hub)
62+
63+
The **Hub-Sync** feature supports two options
64+
1. **Organization Sync:**
65+
Any settings file in the `organizations/<ORG>` directory will be synced to the specific `<ORG>` (Spoke) Admin config Repo subfolder (eg.: <ORG>/.github/). Only updated files are sync'd to the ORG admin config Repo (spokes).
66+
1. **Global Sync:** Any settings file in the `globals/` directory will be synced to the specific `<ORG>` (Spoke) Admin config Repo subfolder (eg.: <ORG>/.github/).
67+
68+
:warning: The actual sync operation is based on the rules defined in the `globals/manifest.yml`. The rules provide fine grained control over the sync targets and sync strategy.
69+
70+
These two options only require that you provide the files you would like to sync, in the correct sub-directory.
71+
72+
#### ✅ Step 5.1: Configure the `manifest.yml` in the 'Master' Safe-Settings Admin Config Repo (Hub)
73+
74+
The `manifest.yml` defines the sync rules for global settings distribution.
75+
- Sample `manifest.yml`
76+
77+
```
78+
rules:
79+
- name: global-defaults
80+
# specify the target ORG(s)
81+
targets:
82+
- "*"
83+
files:
84+
- "*.yml"
85+
86+
# mergeStrategy: merge | overwrite | preserve
87+
# --------------------------------------------
88+
# merge = use a PR to sync files
89+
# overwrite = sync all files to the target ORG(s) (no PR)
90+
mergeStrategy: merge
91+
92+
- name: security-policies
93+
# specify the target ORG(s)
94+
targets:
95+
- "acme-*"
96+
- "foo-bar"
97+
files:
98+
- settings.yml
99+
mergeStrategy: overwrite
100+
101+
# optional toggle, default true
102+
# enabled: false
103+
```
104+
105+
### Example Rule Breakdown
106+
107+
```yaml
108+
- name: global-defaults
109+
targets:
110+
- "*"
111+
files:
112+
- "*.yml"
113+
mergeStrategy: merge
114+
```
115+
- **Purpose:** Sync all YAML files to all organizations, merging changes via PR.
116+
117+
```yaml
118+
- name: security-policies
119+
targets:
120+
- "acme-*"
121+
- "foo-bar"
122+
files:
123+
- settings.yml
124+
mergeStrategy: overwrite
125+
enabled: false
126+
```
127+
128+
- **Purpose:** Overwrite `settings.yml` in specific organizations, but currently disabled.
129+
130+
131+
### `manifest.yml` Reference
132+
133+
The `manifest.yml` file defines synchronization rules for Safe-Settings hub-and-spoke configuration management. Each rule specifies which organizations and files to target, and how to handle synchronization.
134+
135+
### Top-Level Structure
136+
137+
```yaml
138+
rules:
139+
- name: <string>
140+
targets: [<string>, ...]
141+
files: [<string>, ...]
142+
mergeStrategy: <merge|overwrite|preserve>
143+
enabled: <true|false> # optional
144+
# ...additional fields as needed
145+
```
146+
147+
---
148+
149+
### Elements
150+
151+
#### `rules`
152+
- **Type:** Array of objects
153+
- **Description:** List of synchronization rules. Each rule controls how specific files are synced to target organizations.
154+
155+
#### Rule Object
156+
157+
##### `name`
158+
- **Type:** String
159+
- **Description:** Unique identifier for the rule. Used for reference and logging.
160+
- **Example:** `global-defaults`, `security-policies`
161+
162+
##### `targets`
163+
- **Type:** Array of strings
164+
- **Description:** List of organization names or patterns to apply the rule to.
165+
- `"*"`: All organizations
166+
- `"acme-*"`: Organizations with names starting with `acme-`
167+
- `"foo-bar"`: Specific organization
168+
- **Example:**
169+
```yaml
170+
targets:
171+
- "*"
172+
- "acme-*"
173+
- "foo-bar"
174+
```
175+
176+
##### `files`
177+
- **Type:** Array of strings
178+
- **Description:** File patterns to sync. Supports wildcards.
179+
- `"*.yml"`: All YAML files
180+
- `"settings.yml"`: Specific file
181+
- **Example:**
182+
```yaml
183+
files:
184+
- "*.yml"
185+
- "settings.yml"
186+
```
187+
188+
##### `mergeStrategy`
189+
- **Type:** String (`merge`, `overwrite`, `preserve`)
190+
- **Description:** Determines how files are synced:
191+
- `merge`: use a PR to sync files
192+
- `overwrite`: Sync all files, replacing existing ones (direct commit, no PR)
193+
- **Example:**
194+
```yaml
195+
mergeStrategy: merge
196+
```
197+
198+
##### `enabled`
199+
- **Type:** Boolean (optional)
200+
- **Description:** Toggle to enable or disable the rule. Default is `true`.
201+
- **Example:**
202+
```yaml
203+
enabled: false
204+
```
205+
206+
---
207+
208+
### Environment Variables & Inputs Specific to the **Hub-Sync** feature
26209

27210
| Name | Purpose | Default |
28211
|------|---------|---------|
@@ -79,5 +262,4 @@ The following table summarizes the Safe Settings API endpoints:
79262
GET /api/safe-settings/env
80263
```
81264

82-
---
83-
265+
---

0 commit comments

Comments
 (0)