add whitelist / blacklist functionality

Author: UltraProdigy

.github/workflows/org-label-sync.yml

@@ -14,7 +14,7 @@ on:
         type: boolean
         default: false
       repositories:
-        description: "Optional comma-separated subset of discovered repositories"
+        description: "Optional comma-separated subset of repositories after repository-filter rules are applied"
         required: false
         type: string
 

README.md

@@ -36,9 +36,9 @@ The normal flow is:
 |       `-- validate-configs.yml
 |-- config/
 |   |-- auto-pruned-labels.jsonc
-|   |-- blacklisted-repositories.jsonc
 |   |-- labels.jsonc
-|   `-- properties.jsonc
+|   |-- properties.jsonc
+|   `-- repository-filter.jsonc
 `-- scripts/
     |-- export-properties.mjs
     |-- sync-config-labels.mjs
@@ -115,24 +115,37 @@ The starter file is prefilled with GitHub's default labels:
 
 If any of those labels exist on this repo, `Config-Label_Sync` excludes them from `labels.jsonc`. If they exist on target repos, `Org-Label-Sync` deletes them.
 
-### `config/blacklisted-repositories.jsonc`
+### `config/repository-filter.jsonc`
 
-This is the repo blacklist for org sync.
+This controls which repositories `Org-Label-Sync` will target.
 
-By default, `Org-Label-Sync` targets every repo in the configured organization. Any repo listed here is skipped.
+The file uses:
 
-Entries can be either:
+- `useWhitelist`: when `true`, only repositories in `whitelist` are synced; when `false`, all discovered org repositories are synced except those in `blacklist`
+- `whitelist`: repos to include when whitelist mode is enabled
+- `blacklist`: repos to exclude when whitelist mode is disabled
+
+`useWhitelist` defaults to `false`, so blacklist mode is the default behavior.
+
+Entries in either list can be either:
 
 - `repo-name`
 - `owner/repo-name`
 
 Example:
 
 ```jsonc
-[
-  "sandbox-repo",
-  "your-org-name/private-internal-tools"
-]
+{
+  "useWhitelist": false,
+  "whitelist": [
+    "sandbox-repo",
+    "your-org-name/important-repo"
+  ],
+  "blacklist": [
+    "do-not-touch",
+    "your-org-name/private-internal-tools"
+  ]
+}
 ```
 
 ## Workflows
@@ -176,7 +189,8 @@ Validation includes:
 - JSONC parsing
 - required property checks
 - duplicate label detection
-- duplicate blacklist detection
+- repository filter shape and `useWhitelist` validation
+- duplicate whitelist and blacklist detection
 - invalid colors
 - invalid repo names
 - overlap detection between `labels.jsonc` and `auto-pruned-labels.jsonc`
@@ -193,7 +207,7 @@ Inputs:
 
 - `dry_run`: preview changes without writing them
 - `delete_missing`: override `deleteMissingByDefault` for the run
-- `repositories`: optional comma-separated subset of discovered repositories
+- `repositories`: optional comma-separated subset of repositories after `repository-filter.jsonc` is applied
 
 What it does:
 
@@ -202,7 +216,7 @@ What it does:
 3. Loads shared settings from `config/properties.jsonc`
 4. Validates the updated config
 5. Discovers repos in the configured organization
-6. Skips repos in `config/blacklisted-repositories.jsonc`
+6. Applies `config/repository-filter.jsonc`
 7. Creates or updates labels from `config/labels.jsonc`
 8. Deletes labels listed in `config/auto-pruned-labels.jsonc`
 9. Optionally deletes any other unmanaged labels if `delete_missing` or `deleteMissingByDefault` is enabled
@@ -224,14 +238,14 @@ That token needs enough access to:
 2. Create the sync token secret in the repo.
 3. Update `config/properties.jsonc` for your org and repo.
 4. Adjust `config/auto-pruned-labels.jsonc` if you want a different always-delete list.
-5. Add any excluded repos to `config/blacklisted-repositories.jsonc`.
+5. Configure `config/repository-filter.jsonc` for blacklist mode or whitelist mode.
 6. Set the labels on this repository to the label set you want to manage.
 7. Run `Config-Label_Sync` once if you want to populate `config/labels.jsonc` immediately.
 8. Run `Org-Label-Sync` to propagate the labels across the organization.
 
 ## Safe Defaults
 
 - `labels.jsonc` starts empty until you define or sync labels on this repo
-- all repos in the org are targeted unless blacklisted
+- all repos in the org are targeted unless excluded by `repository-filter.jsonc`
 - GitHub default labels are auto-pruned by default
 - deleting unmanaged labels is off by default unless you enable it

config/blacklisted-repositories.jsonc

@@ -0,0 +1,17 @@
+// Set to true to sync only the repositories listed in "whitelist".
+// Set to false to sync every discovered org repository except those listed in "blacklist".
+{
+  "useWhitelist": false,
+
+  // Used only when "useWhitelist" is true.
+  "whitelist": [
+    // "sandbox-repo",
+    // "your-org-name/important-repo"
+  ],
+
+  // Used only when "useWhitelist" is false.
+  "blacklist": [
+    // "do-not-touch",
+    // "your-org-name/private-internal-tools"
+  ]
+}

config/repository-filter.jsonc

@@ -12,7 +12,7 @@ const workspaceRoot = process.cwd();
 const propertiesPath = path.join(workspaceRoot, "config", "properties.jsonc");
 const labelsPath = path.join(workspaceRoot, "config", "labels.jsonc");
 const autoPrunedLabelsPath = path.join(workspaceRoot, "config", "auto-pruned-labels.jsonc");
-const blacklistedRepositoriesPath = path.join(workspaceRoot, "config", "blacklisted-repositories.jsonc");
+const repositoryFilterPath = path.join(workspaceRoot, "config", "repository-filter.jsonc");
 
 const validateOnly = process.argv.includes("--validate-only");
 const dryRun = validateOnly || process.env.DRY_RUN === "true";
@@ -130,25 +130,42 @@ function assertNoLabelOverlap(desiredLabels, deleteLabels) {
   );
 }
 
-function validateBlacklistedRepositories(blacklist) {
-  assert(Array.isArray(blacklist), "config/blacklisted-repositories.jsonc must contain an array.");
+function validateRepositoryEntries(entries, configKey) {
+  assert(Array.isArray(entries), `config/repository-filter.jsonc field "${configKey}" must contain an array.`);
   const seen = new Set();
-  return new Set(blacklist.map((entry, index) => {
-    assert(typeof entry === "string" && entry.trim(), `Blacklist entry at index ${index} must be a non-empty string.`);
+  return new Set(entries.map((entry, index) => {
+    assert(typeof entry === "string" && entry.trim(), `"${configKey}" entry at index ${index} must be a non-empty string.`);
 
     const name = entry.trim();
     assert(
       isRepositoryName(name) || isFullRepositoryName(name),
-      `Blacklist entry "${name}" must be either "repo-name" or "owner/repo-name".`,
+      `"${configKey}" entry "${name}" must be either "repo-name" or "owner/repo-name".`,
     );
 
     const key = normalizeRepositoryRef(name);
-    assert(!seen.has(key), `Duplicate blacklist entry detected: "${name}".`);
+    assert(!seen.has(key), `Duplicate "${configKey}" entry detected: "${name}".`);
     seen.add(key);
     return key;
   }));
 }
 
+function validateRepositoryFilter(repositoryFilter) {
+  assert(
+    repositoryFilter && typeof repositoryFilter === "object" && !Array.isArray(repositoryFilter),
+    "config/repository-filter.jsonc must contain an object.",
+  );
+
+  if (repositoryFilter.useWhitelist !== undefined) {
+    assert(typeof repositoryFilter.useWhitelist === "boolean", 'config/repository-filter.jsonc field "useWhitelist" must be a boolean.');
+  }
+
+  return {
+    useWhitelist: repositoryFilter.useWhitelist ?? false,
+    whitelist: validateRepositoryEntries(repositoryFilter.whitelist ?? [], "whitelist"),
+    blacklist: validateRepositoryEntries(repositoryFilter.blacklist ?? [], "blacklist"),
+  };
+}
+
 async function githubRequest(token, method, apiPath, body) {
   const response = await fetch(`https://api.github.com${apiPath}`, {
     method,
@@ -210,14 +227,21 @@ async function getOrganizationRepositories(token, orgName) {
   }
 }
 
-function filterRepositories(repositories, orgName, blacklist) {
+function filterRepositories(repositories, orgName, repositoryFilter) {
   return repositories
     .filter((repository) => {
       const shortName = normalizeRepositoryRef(repository.name);
       const fullName = normalizeRepositoryRef(repository.full_name);
       const orgScopedName = normalizeRepositoryRef(`${orgName}/${repository.name}`);
+      const matchesFilter = (entries) => (
+        entries.has(shortName) || entries.has(fullName) || entries.has(orgScopedName)
+      );
+
+      if (repositoryFilter.useWhitelist) {
+        return matchesFilter(repositoryFilter.whitelist);
+      }
 
-      return !blacklist.has(shortName) && !blacklist.has(fullName) && !blacklist.has(orgScopedName);
+      return !matchesFilter(repositoryFilter.blacklist);
     })
     .sort((left, right) => left.full_name.localeCompare(right.full_name));
 }
@@ -243,7 +267,7 @@ function applyTargetRepositoryFilter(repositories) {
 
   assert(
     missing.length === 0,
-    `Requested repositories were not found in the discovered org repository set after blacklist filtering: ${missing.join(", ")}.`,
+    `Requested repositories were not found in the discovered org repository set after repository-filter processing: ${missing.join(", ")}.`,
   );
 
   return selected;
@@ -360,10 +384,12 @@ async function main() {
   const labels = validateLabels(await readJsonc(labelsPath));
   const deleteLabels = validateDeleteLabels(await readJsonc(autoPrunedLabelsPath));
   assertNoLabelOverlap(labels, deleteLabels);
-  const blacklistedRepositories = validateBlacklistedRepositories(await readJsonc(blacklistedRepositoriesPath));
+  const repositoryFilter = validateRepositoryFilter(await readJsonc(repositoryFilterPath));
+  const activeFilterCount = repositoryFilter.useWhitelist ? repositoryFilter.whitelist.size : repositoryFilter.blacklist.size;
+  const activeFilterMode = repositoryFilter.useWhitelist ? "whitelist" : "blacklist";
 
   console.log(
-    `Loaded ${labels.length} managed labels, ${deleteLabels.length} auto-pruned labels, and ${blacklistedRepositories.size} blacklisted repositories.`,
+    `Loaded ${labels.length} managed labels, ${deleteLabels.length} auto-pruned labels, and ${activeFilterCount} active repository filter entries from config/repository-filter.jsonc (mode=${activeFilterMode}).`,
   );
 
   if (validateOnly) {
@@ -378,15 +404,15 @@ async function main() {
 
   const discoveredRepositories = await getOrganizationRepositories(token, orgName);
   const repositories = applyTargetRepositoryFilter(
-    filterRepositories(discoveredRepositories, orgName, blacklistedRepositories),
+    filterRepositories(discoveredRepositories, orgName, repositoryFilter),
   );
 
   console.log(
-    `Discovered ${discoveredRepositories.length} repositories in ${orgName}; ${repositories.length} remain after blacklist filtering.`,
+    `Discovered ${discoveredRepositories.length} repositories in ${orgName}; ${repositories.length} remain after repository-filter processing.`,
   );
 
   if (repositories.length === 0) {
-    console.log("No repositories remain after blacklist and optional subset filtering. Nothing to sync.");
+    console.log("No repositories remain after repository-filter processing and optional subset filtering. Nothing to sync.");
     return;
   }